Re: uri templates: escaping & defaults

On Jul 16, 2011, at 10:09 AM, Robert Brewer wrote:

> Roy T. Fielding wrote:
>> On Jul 14, 2011, at 6:18 PM, Roy T. Fielding wrote:
>> 
>>> On Jul 14, 2011, at 6:06 PM, Robert Brewer wrote:
>>> 
>>>> Roy T. Fielding wrote:
>>>>> On Jul 13, 2011, at 9:19 AM, Manger, James H wrote:
>>>>>> 6.
>>>>>> There are no examples with defaults for more than 1 variable.
>>>>>> For example, add "x{/var|1st,empty|2nd}" to section 2.5
>>>>>> "Value Defaults". The very long list of examples in this
>>>>>> section is not good sign to me that this feature's design
>>>>>> is intuitive.
>>>>> 
>>>>> Right.  The reason is simply that the examples get too long.
>>>>> 
>>>>> Anyway, I was thinking about defaults this morning and realized
>> that
>>>>> I don't have any use case for them.  That is, if we assume that
> the
>>>>> server is telling the client what values are to okay to place in
>> the
>>>>> variables, then why would the server ever tell the client that the
>>>>> variable is undefined?
>>>>> 
>>>>> The only use case that I know of is that it allows the server to
>>>>> state what parts of the URI space are never empty.  However, I
>> can't
>>>>> think of anyone who needs that.  Are there other use cases?
>>>> 
>>>> I've seen (and written) plenty of API's where /foos/bar/baz makes
>> sense
>>>> but /foos//baz doesn't make sense (at best, or breaks at worst). It
>>>> would be useful to be able to write something like /foos/{bar!}/baz
>>>> where the "!" character constrains the value to be supplied and not
>>>> empty.
>>> 
>>> But that's why we have /foos{/bar}/baz
>> 
>> er, never mind -- that would eliminate "/foos//baz" but not
> "/foos/baz"
>> 
>> Anyway, the point I was making earlier is that if the client is
>> only using values that has been given to it by the server, then bar
>> will never be empty.  I think that is a better solution than a
>> must-be-defined mark because there is nothing useful that a client
>> can do with a template that says it is an error.
> 
> Draft 05 says "Our expectation is that an application constructing URIs
> according to the template will be provided with an appropriate set of
> values for the variables being substituted and will be able to cope with
> any errors that might occur when the resulting URI is used for name
> resolution or access."
> 
> Combining that with what you've said above, it seems like you would
> expect even a user-agent to show a predetermined set of values to a
> user, and not let them supply whatever value(s) they want. But if that's
> true, then I can't see how one of the first examples in the spec is
> useful to anybody: http://example.com/search{?q,lang}. It's
> counterintuitive to see that URL and expect the server to only let me
> pick "cat" or "dog" for q. Or are we saying that that's a fine pattern
> in query strings, but not path segments?

No, there are certainly some examples where the possible value set is
truly open-ended.  That is one of them.  Note that having a default for
q would also be nonsensical.  Note also that an empty query on Google
is a separate resource.

I think what you are getting at is that it makes sense to have an
indicator that this variable must be defined (and also non-empty?).
But is that something we need in the template syntax?  IMO, that is
the kind of information that would be placed in the variable definition
outside of the template -- in some WADL or javascript or opensearch
or whatever else is using the template.

> Machine clients probably wouldn't be able to "do anything useful" when
> they can't supply a required value, unless you count "raise an error" as
> useful. I'd like that behavior in my clients. User-agents, of course,
> could notify the user and ask for a non-empty value.

Keep in mind that a user agent of that sort (browser) would never see
a template.  They would see a FORM instead, and that form would have
the same mechanisms for validation as existing forms.

....Roy

Received on Monday, 18 July 2011 03:12:07 UTC