URI Template: query param name different than variable name

I expect one of the most common use cases for URI templates will be  
building query parameters using variable names defined by some  
specification. For instance, OpenSearch defines variables such as  
'searchTerms', 'count', 'startPage', 'language', 'inputEncoding'. Many  
web sites will want to use different query parameter names to carry  
the values of these variables. For instance, 'q' for 'searchTerms',  
'page' for 'startPage', 'lang' for 'language' etc. This cannot be done  
well with the current working draft.

The working draft says [in 2.5 Variables]:
"The variable names serve multiple purposes: documentation for what  
kinds of values are expected, identifiers for associating values  
within a URI Template processor, and the string to use for each key on  
key=value substitutions."

I disagree with this restriction. A URI template should allow the  
template author to choose "the string to use for each key",  
independently of what another party has decided for the variable name  
(for documentation and as an identifier).

Of course a template author can write "?q={searchTerms}&p= 
{startPage}". However, the URI Template spec has a '?' operator to do  
better than this -- allowing the whole "&p=" part to be omitted when  
no 'startPage' is defined, for instance.


I suggest changing the '?' operator to have a form like "{?name=[var]}".
If 'var' is omitted (the template is "{?name=}") then (as with the  
current draft) 'name' is used as both the variable name and the query  
parameter name.


'=' is currently used to introduce a default value: {[op]var 
[=default]}. However, you don't need to use an operator and a default  
together. For instance, in the current syntax "{?startPage=1}" can be  
written as "?startPage={startPage=1} -- there is always a value (from  
the variable or the default) so the operator-related parts will always  
be present so they can be 'literals' outside the { } brackets.


Please also require a template processor to be smart about a '?'  
operator: substituting '?...' if it is the first query param (no  
previous '?' in the URI being built), or substituting '&...' otherwise.


If this {?name=[var]} proposal is accepted it might be worth making  
some other changes to keep the syntax consistent. Below is one idea:
   {[op [name=]] [vartype] varname [modifier] [| default]}
* add a ',' operator, instead of supporting a variable-list in each  
{...} expression
* 'default' is a default for the whole expression, not just the  
variable value excluding modifiers
* use 'name' as the variable name if 'varname' is an empty string

James Manger

Received on Wednesday, 11 November 2009 14:06:59 UTC