Re: URI Template: query param name different than variable name

Sorry for the lateness of this reply -- I tried to address these
issues in the draft last December and then got side-tracked by
family issues.

On Nov 11, 2009, at 6:06 AM, James Manger wrote:

> 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).

The variable names are defined inside the template, so I don't
see how the template author is being disenfranchised here.
However, I see your point about there being external schemas
that a resource owner might want to use as a mapping from
variable names to standardized definitions.

I think that such a feature should be handled outside the URI
template itself, with only minimal indication that a variable
corresponds to a given profile.  I ran into a similar problem
with the way I was indicating variable types as a list or
associative array: they are insufficiently self-descriptive
to be understood by clients without a profile anyway.

Likewise, it would be nice to be able to refer to a standard
set of variables like OpenSearch provides with a single
variable name.

I removed the variable types from the template grammar and
replaced them with explode modifiers ("*" or "+" at the end
of a variable name) to indicate that the variable is a
placeholder for some wider structured or schema-directed
substitutions.  The goal here is to make the template as
small as possible and let the variable name be explained
outside the template, e.g.

   Link-Template: <http://example.com/find{?q,lang};
        profile="http://opensearch.org/1.1";
        map="q:searchTerms,lang:language"

or simply

   Link-Template: <http://example.com/find{?OpenSearch*};
        profile="http://opensearch.org/1.1"

   

> 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.

But that introduces a whole host of problems.  Visually, it
looks like the second variable is a default value (even if
we were to change the default syntax).  It also adds
variables to the template that describe the implementation
rather than the end-result.  And a complex schema like
OpenSearch would end up with a huge, ugly template.

> '=' 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.

I think that introducing a recursive syntax for templates
would be dangerous.  Tempting, but a denial-of-service attack
just waiting to happen.

> 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.

The template processor doesn't know where it is in the URI.
Is such a feature still needed with the profile idea above?

> 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

But then we can't represent common idioms like imagemap,
coordinates, etc.  And it is ugly.

> * 'default' is a default for the whole expression, not just the variable value excluding modifiers

But then we can't easily define path segment defaults
within a hierarchy.

> * use 'name' as the variable name if 'varname' is an empty string

Which would be inconsistent with the other operators.

I think these are all good ideas, but I am trying to maintain
a balance between the simple and short templates needed for
exchanging links and the more complex needs of existing
service interfaces.  In general, I think the simple forms
should win, since the complex service interfaces already suck.

....Roy

Received on Friday, 26 February 2010 02:01:21 UTC