Fwd: I-D Action: draft-gregorio-uritemplate-05.txt

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Fwd: I-D Action: draft-gregorio-uritemplate-05.txt

Roy T. Fielding
I have made another attempt to get consensus on the URI Template
spec by removing some of the obscure bits of draft 04 and splitting
the templates into four levels of implementation.  Unfortunately,
I did not have enough time to go back though all the comments on
draft 04 from last year, and there are still a few sections that
are TBD.

I chose the levels based on perceived complexity, but am not wedded
to any specific order or clustering.  For example, it would probably
make more sense to have prefix modifiers in Level 2.

The only radical change to the syntax is changing the default
specifier delimiter from "=" to "|" and then allowing "=" to
appear in the default value.  The suffix, remainder, and labelled
explode modifiers have been removed.

If you have an implementation of URI Templates (or feel like
writing one), please let us know if any of these changes are
unwelcome.  If there are parts of the syntax that need to be
postponed to higher levels (or removed altogether), then let us
all know.

As usual, all draft formats and a diff from 04 are available at

   http://uri-templates.googlecode.com/svn/trunk/spec/

Cheers,

Roy T. Fielding                     <http://roy.gbiv.com/>
Principal Scientist, Adobe Systems  <http://adobe.com/enterprise>

Begin forwarded message:

> From: [hidden email]
> Date: July 11, 2011 4:33:52 PM PDT
> To: [hidden email]
> Subject: I-D Action: draft-gregorio-uritemplate-05.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
> Title           : URI Template
> Author(s)       : Joe Gregorio
>                          Roy T. Fielding
>                          Marc Hadley
>                          Mark Nottingham
>                          David Orchard
> Filename        : draft-gregorio-uritemplate-05.txt
> Pages           : 28
> Date            : 2011-07-11
>
>   A URI Template is a compact sequence of characters for describing a
>   range of Uniform Resource Identifiers through variable expansion.
>   This specification defines the URI Template syntax and the process
>   for expanding a URI Template into a URI reference, along with
>   guidelines for the use of URI Templates on the Internet.
>
> Editorial Note (to be removed by RFC Editor)
>
>   To provide feedback on this Internet-Draft, join the W3C URI mailing
>   list (http://lists.w3.org/Archives/Public/uri/) [1].
>
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-05.txt


Reply | Threaded
Open this post in threaded view
|

Re: Fwd: I-D Action: draft-gregorio-uritemplate-05.txt

Marc Portier-2
Hi Roy,

Haven't got the time yet to update the js implementation, but wanted to
already give some feedback on a first read...

[general]
It surely gives a simplified and more natural first impression then
previous iteration.  But I should probably get into the implementation
details before re-asserting that.


[section 1.2]
* The Level 2 examples already use {x}, so I guess you should add it in
the section of defined variables:   x := "1024"

* The Level 3 examples contain a glitch I think:
{+path,x}/here   should expand to /foo/bar1024/here
                           and not /foo/bar/1024/here

* The Level 4 examples all expand {keys} to a bigger structural content
then provided in the variable-definition section

I suppose it should be keys := [("semi", ";"),("dot","."),("comma","'")]
(comma is not in the definition, but it is in all expansions)


[section 3.2.4]
* samples are not using the .-dot-prefix label expansion, but the simple
string expansion

[section 3.2.5]
* similar: samples are not using the /-slash-prefix path expansion


And one comment of a less serious nature:

[section 1]
*  somehow
   http://example.com/search?q=chien&lang=fr
makes more sense then
   http://example.com/search?q=dog&lang=fr


Anyway, I hope the other comments are more useful, and I hope to get
back soon with feedback from my updated js-implementation.

regards,
-marc=

On 12-07-11 02:40, Roy T. Fielding wrote:

> I have made another attempt to get consensus on the URI Template
> spec by removing some of the obscure bits of draft 04 and splitting
> the templates into four levels of implementation.  Unfortunately,
> I did not have enough time to go back though all the comments on
> draft 04 from last year, and there are still a few sections that
> are TBD.
>
> I chose the levels based on perceived complexity, but am not wedded
> to any specific order or clustering.  For example, it would probably
> make more sense to have prefix modifiers in Level 2.
>
> The only radical change to the syntax is changing the default
> specifier delimiter from "=" to "|" and then allowing "=" to
> appear in the default value.  The suffix, remainder, and labelled
> explode modifiers have been removed.
>
> If you have an implementation of URI Templates (or feel like
> writing one), please let us know if any of these changes are
> unwelcome.  If there are parts of the syntax that need to be
> postponed to higher levels (or removed altogether), then let us
> all know.
>
> As usual, all draft formats and a diff from 04 are available at
>
>     http://uri-templates.googlecode.com/svn/trunk/spec/
>
> Cheers,
>
> Roy T. Fielding<http://roy.gbiv.com/>
> Principal Scientist, Adobe Systems<http://adobe.com/enterprise>
>
> Begin forwarded message:
>
>> From: [hidden email]
>> Date: July 11, 2011 4:33:52 PM PDT
>> To: [hidden email]
>> Subject: I-D Action: draft-gregorio-uritemplate-05.txt
>> Reply-To: [hidden email]
>>
>> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>>
>> Title           : URI Template
>> Author(s)       : Joe Gregorio
>>                           Roy T. Fielding
>>                           Marc Hadley
>>                           Mark Nottingham
>>                           David Orchard
>> Filename        : draft-gregorio-uritemplate-05.txt
>> Pages           : 28
>> Date            : 2011-07-11
>>
>>    A URI Template is a compact sequence of characters for describing a
>>    range of Uniform Resource Identifiers through variable expansion.
>>    This specification defines the URI Template syntax and the process
>>    for expanding a URI Template into a URI reference, along with
>>    guidelines for the use of URI Templates on the Internet.
>>
>> Editorial Note (to be removed by RFC Editor)
>>
>>    To provide feedback on this Internet-Draft, join the W3C URI mailing
>>    list (http://lists.w3.org/Archives/Public/uri/) [1].
>>
>>
>> A URL for this Internet-Draft is:
>> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-05.txt
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: I-D Action: draft-gregorio-uritemplate-05.txt

Marc Portier-2


On 12-07-11 21:58, Marc Portier wrote:
>
> * The Level 3 examples contain a glitch I think:
> {+path,x}/here should expand to /foo/bar1024/here
> and not /foo/bar/1024/here
>

correction: /foo/bar,1024/here  should be the outcome.
sorry for the confusion

-marc=


Reply | Threaded
Open this post in threaded view
|

uri templates: {?var}

Manger, James H
In reply to this post by Roy T. Fielding
It is great to see some more progress on URI templates <draft-gregorio-uritemplate-05>. Thanks Roy.

1.
The form-style query expansions {?var} needs to substitute '?' or '&' based on whether or not a '?' already appears in the URI output string being constructed. The text about the '?' operator in 1.1 "Overview" isn't clear on this point. It says '?' is used for the first variable with a defined value in the expression. This is true for the specific example used in the overview, but not true in general (when a template might have some query parameters as literals).

Suggested text:

  http://www.example.com/foo{?query,number}
                            \_____________/
                              |
  For each variable in ['query', 'number'] that has a defined value:
  substitute "?" or "&"; the variable name; "="; and the variable's
  value. The initial character substituted is "?" if, and only if,
  no "?" is already present in the URI output string being built.


--
James Manger


Reply | Threaded
Open this post in threaded view
|

uri templates: escaping & defaults

Manger, James H
In reply to this post by Roy T. Fielding
A couple of comments on escaping and defaults in <draft-gregorio-uritemplate-05>.

2. (being really picky)
Append "or a percent character" to the last sentence of section 1.1 "Overview" since "%" has a special function in URIs but isn't actually in the reserved set.

    ... the result of template processing can be rendered as an
  IRI by transforming each of the pct-encoded sequences to their
  corresponding Unicode character if that character is not in the
  reserved set or a percent character.


3.
Section 2 "Syntax" (3rd paragraph) says a pct-encoded char within a template is decoded before further processing unless the char is in the reserved set.
This is not quite right. For instance, a literal part of a template can legitimately include "%7B" (since a URI can), but decoding this to "{" would wreck parsing the template into expressions. "{" is not in the reserved set. Similarly, decoding a pct-encoded "}" or "|" is a problem.

I think we need to do all the parsing first (into <literal>, <operator>, <varname>, <modifier>, <default>), then decode any pct-encoding in <varname> (regardless of whether the char is in the reserved set). The other fields don't need decoding, except perhaps <default>. Decoding <default> should only be required to support commas in default values. My preferred solution is to have 1 default per <expression> (not 1 per <varspec>), in which case decoding is unnecessary for this field.


4. (typo)
Section 2.4.1 "Prefix Values": change <offset> to <max-length>.


5.
Why can <default> values include "=", but no other <reserved> char [section 2.5 "Value Defaults"]?
Any <reserved> except comma can be allowed without making the syntax ambiguous so we should allow them.


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.


7.
Section 3 "Expansion" says that if an error occurs with an expression, then "the expression SHOULD be copied to the result unexpanded". Should the expression at least be pct-encoded (eg the "{" becomes "%7B")? Should <reserved> chars in the expression be pct-encoded?



--
James Manger


Reply | Threaded
Open this post in threaded view
|

Re: uri templates: escaping & defaults

Roy T. Fielding
On Jul 13, 2011, at 9:19 AM, Manger, James H wrote:

> A couple of comments on escaping and defaults in <draft-gregorio-uritemplate-05>.
>
> 2. (being really picky)
> Append "or a percent character" to the last sentence of section 1.1 "Overview" since "%" has a special function in URIs but isn't actually in the reserved set.
>
>    ... the result of template processing can be rendered as an
>  IRI by transforming each of the pct-encoded sequences to their
>  corresponding Unicode character if that character is not in the
>  reserved set or a percent character.

Ah, yes, thanks.

> 3.
> Section 2 "Syntax" (3rd paragraph) says a pct-encoded char within a template is decoded before further processing unless the char is in the reserved set.
> This is not quite right. For instance, a literal part of a template can legitimately include "%7B" (since a URI can), but decoding this to "{" would wreck parsing the template into expressions. "{" is not in the reserved set. Similarly, decoding a pct-encoded "}" or "|" is a problem.

Good catch.


> I think we need to do all the parsing first (into <literal>, <operator>, <varname>, <modifier>, <default>), then decode any pct-encoding in <varname> (regardless of whether the char is in the reserved set). The other fields don't need decoding, except perhaps <default>. Decoding <default> should only be required to support commas in default values. My preferred solution is to have 1 default per <expression> (not 1 per <varspec>), in which case decoding is unnecessary for this field.
>
>
> 4. (typo)
> Section 2.4.1 "Prefix Values": change <offset> to <max-length>.

Yep, leftover from name change.

> 5.
> Why can <default> values include "=", but no other <reserved> char [section 2.5 "Value Defaults"]?
> Any <reserved> except comma can be allowed without making the syntax ambiguous so we should allow them.

Yep, that was one of the things you mentioned before that I forgot
to fix, though see below ...

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

It would simplify the examples and algorithm descriptions a lot
if we removed defaults.

> 7.
> Section 3 "Expansion" says that if an error occurs with an expression, then "the expression SHOULD be copied to the result unexpanded". Should the expression at least be pct-encoded (eg the "{" becomes "%7B")? Should <reserved> chars in the expression be pct-encoded?

My goal was to provide the result for error diagnostics, not as
a valid URI.  I should have actually said that in the text.

....Roy


Reply | Threaded
Open this post in threaded view
|

Re: uri templates: {?var}

Roy T. Fielding
In reply to this post by Manger, James H
On Jul 13, 2011, at 7:17 AM, Manger, James H wrote:

> It is great to see some more progress on URI templates <draft-gregorio-uritemplate-05>. Thanks Roy.
>
> 1.
> The form-style query expansions {?var} needs to substitute '?' or '&' based on whether or not a '?' already appears in the URI output string being constructed.

I disagree.  I do not want the expression processor to need
to know the state of the surrounding URI reference.  We then
get into a discussion about what happens when {+foo}{?this}
is the template and foo := "hello?".

> The text about the '?' operator in 1.1 "Overview" isn't clear on this point. It says '?' is used for the first variable with a defined value in the expression. This is true for the specific example used in the overview, but not true in general (when a template might have some query parameters as literals).

In that case, the template should not be using the ? operator.
It should be using foo?literal=here&var={variable}

The description does have a problem with defaults, though.

....Roy
Reply | Threaded
Open this post in threaded view
|

Re: I-D Action: draft-gregorio-uritemplate-05.txt

Roy T. Fielding
In reply to this post by Marc Portier-2
On Jul 13, 2011, at 4:55 AM, Marc Portier wrote:
> On 12-07-11 21:58, Marc Portier wrote:
>>
>> * The Level 3 examples contain a glitch I think:
>> {+path,x}/here should expand to /foo/bar1024/here
>> and not /foo/bar/1024/here
>>
>
> correction: /foo/bar,1024/here  should be the outcome.

Yep.  At least I got it right for Level 2.

....Roy


Reply | Threaded
Open this post in threaded view
|

RE: uri templates: escaping & defaults

Robert Brewer-4
In reply to this post by Roy T. Fielding
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.


Robert Brewer
[hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: uri templates: escaping & defaults

Roy T. Fielding
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

....Roy


Reply | Threaded
Open this post in threaded view
|

RE: uri templates: {?var}

Manger, James H
In reply to this post by Roy T. Fielding
Roy,

>> The form-style query expansions {?var} needs to substitute '?' or '&' based on whether or not a '?' already appears in the URI output string being constructed.

> I disagree.  I do not want the expression processor to need
to know the state of the surrounding URI reference.

Not having to know the state of the URI being built is a very MINOR benefit for the (few) developers of template processor libraries. An {?var} operator that looks for any '?' in that state is a MAJOR benefit to (many many) template authors.

Avoiding the surrounding state only works if ALL the query parameters are listed in a single {?var1,var2...} expression. I expect there to be lots of situations where that will not work, or isn't convenient.
* Many situations will have some parameters values fixed by the template author.
* Many situations will use a parameter name in the URI that is different from the variable name (eg "foo?q={searchTerm}"), which cannot be expressed in a {?var} expression as currently specified.
* Some situations will build a template by concatenating expressions to a configured base. You cannot concatenate {?var} if the base might have a query part.


> We then get into a discussion about what happens when {+foo}{?this}
is the template and foo := "hello?".

It would expand to "hello?&this=...", which still delivers a parameter named "this" to CGI scripts.
The current text is worse in this situation. It expands to "hello??this=...". A CGI script will NOT see a "this" parameter as it expects. Instead, it will see a parameter named "?this".

What should happen if foo := "hello?fmt=xml"? Expanding to a URI with 'fmt' and 'this' query parameters is the answer with the least surprise.


>> The text about the '?' operator in 1.1 "Overview" isn't clear on this point. It says '?' is used for the first variable with a defined value in the expression. This is true for the specific example used in the overview, but not true in general (when a template might have some query parameters as literals).

> In that case, the template should not be using the ? operator.
It should be using foo?literal=here&var={variable}

If a template should use
"foo?literal=here&var={var}" instead of "foo?literal=here{?var}"
why not use
"foo?var1={var1}&var2={var2}" instead of "foo{?var1,var2}"
and drop the whole operator?

The draft 05 text will be nasty for authors that are modifying a template that uses "{?a,b,c,x,y,z}". To add a fmt=xml parameter they have to change all the other parameters: "?fmt=xml&a={a}&b={b}&c={c}&x={x}&y={y}&z={z}".



--
James Manger

Reply | Threaded
Open this post in threaded view
|

Re: uri templates: {?var}

Roy T. Fielding
On Jul 14, 2011, at 6:26 PM, Manger, James H wrote:
> Not having to know the state of the URI being built is a very MINOR benefit for the (few) developers of template processor libraries. An {?var} operator that looks for any '?' in that state is a MAJOR benefit to (many many) template authors.

It isn't a minor benefit -- it means that each expression can be
expanded in parallel instead of sequentially from left to right,
that the template processor does not need to include a URI parser,
and that each expression can be considered in isolation and thus
not be subject to several factorial more potential test cases.

> If a template should use
> "foo?literal=here&var={var}" instead of "foo?literal=here{?var}"
> why not use
> "foo?var1={var1}&var2={var2}" instead of "foo{?var1,var2}"
> and drop the whole operator?

Because foo{?var1,var2} is the common case and far easier to read.

> The draft 05 text will be nasty for authors that are modifying a template that uses "{?a,b,c,x,y,z}". To add a fmt=xml parameter they have to change all the other parameters: "?fmt=xml&a={a}&b={b}&c={c}&x={x}&y={y}&z={z}".

If an author has the ability to modify the template, they
would modify it to be {?fmt,a,b,c,x,y,z}.  If a template has
a hundred different variables that can't be described in a
more rational way like an explode variable, then the site sucks.
The explode syntax was intended to make that case a little less
ugly, but I really don't care to turn templates into yet another
way to design bad sites.

....Roy
Reply | Threaded
Open this post in threaded view
|

Re: uri templates: escaping & defaults

Roy T. Fielding
In reply to this post by Roy T. Fielding
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.

....Roy


Reply | Threaded
Open this post in threaded view
|

RE: uri templates: {?var}

Manger, James H
In reply to this post by Roy T. Fielding
>> Not having to know the state of the URI being built is a very MINOR benefit for the (few) developers of template processor libraries. An {?var} operator that looks for any '?' in that state is a MAJOR benefit to (many many) template authors.

Roy answered:
>It isn't a minor benefit -- it means that each expression can be
expanded in parallel instead of sequentially from left to right,
that the template processor does not need to include a URI parser,
and that each expression can be considered in isolation and thus
not be subject to several factorial more potential test cases.

URIs are too small (a few KB) for anyone to bother to parallelize the expansion.

Expressions cannot quite be considered in isolation as the value of a variable MUST be the same in all expressions that include the variable.

You don't need a URI parser to look for a '?' in a string.


> Because foo{?var1,var2} is the common case and far easier to read.

All the query parameters being variables for the user to provide, and all variable names matching the parameter names is probably the most common case.

Do you really think a parameter with a fixed value, or a parameter name not matching a variable name will be much, much less common? I don't. I think those cases will be quite common so they should be smoothly supported by the template syntax.


HTML forms have a very widely used <input type="hidden"> element, which is strong evidence that authors (of forms or templates) will often want to include fixed parameters. We could assume that protocols using templates will invent their own versions of <input type="hidden">, but it is much simpler to include the fixed parameters directly in the template (and not punishing that choice by making {?var} break in those situations).


--
James Manger

Reply | Threaded
Open this post in threaded view
|

Re: I-D Action: draft-gregorio-uritemplate-05.txt

Roy T. Fielding
In reply to this post by Marc Portier-2
On Jul 12, 2011, at 12:58 PM, Marc Portier wrote:

> Hi Roy,
>
> Haven't got the time yet to update the js implementation, but wanted to already give some feedback on a first read...
>
> [general]
> It surely gives a simplified and more natural first impression then previous iteration.  But I should probably get into the implementation details before re-asserting that.
>
>
> [section 1.2]
> * The Level 2 examples already use {x}, so I guess you should add it in the section of defined variables:   x := "1024"

I've changed the example to use var instead.

> * The Level 3 examples contain a glitch I think:
> {+path,x}/here   should expand to /foo/bar1024/here
>                          and not /foo/bar/1024/here

Fixed.

>
> * The Level 4 examples all expand {keys} to a bigger structural content then provided in the variable-definition section
>
> I suppose it should be keys := [("semi", ";"),("dot","."),("comma","'")]
> (comma is not in the definition, but it is in all expansions)

Oops, thanks.

> [section 3.2.4]
> * samples are not using the .-dot-prefix label expansion, but the simple string expansion
>
> [section 3.2.5]
> * similar: samples are not using the /-slash-prefix path expansion

More paste-o's.  Fixed.

> And one comment of a less serious nature:
>
> [section 1]
> *  somehow
>  http://example.com/search?q=chien&lang=fr
> makes more sense then
>  http://example.com/search?q=dog&lang=fr

Huh, I could have sworn that I already did that last year.
I even remember looking it up.  Thanks for the careful read,

....Roy
Reply | Threaded
Open this post in threaded view
|

RE: uri templates: escaping & defaults

Robert Brewer-4
In reply to this post by Roy T. Fielding
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?

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.


Robert Brewer
[hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: uri templates: escaping & defaults

Roy T. Fielding
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