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

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

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

Roy T. Fielding-2
[second attempt to send this]

I managed to submit a new draft, just before the deadline,
with the obsolete sections removed and the sections that
still need writing marked as TBD.

The current issues (that I am aware of) include:

1) error handling -- as Joe noted, we can improve consistency
by making every error in the template result in a semi-expanded
result string and error indicator, rather than nulling
the result string and returning immediately.  My preference is
to copy bad expressions to the result, continue processing, and
indicate an error occurred to the caller.  This allows the
calling application to use the result string to point out
where the processing failed.

2) reserved substitution -- this is currently allowed only
by the "+" operator.  A suggestion by Mike Burrows is that the
"+" operator be changed into a variable name prefix so that
it can be selectively applied to any variable in any expression.
In addition to the added power, I found that a prefix would
simplify the value expansion description (and algorithm).
However, I have not made that change yet in 04.  Would such
a change be compatible with XRD and other applications?

3) I introduced explode modifiers, with the named variable
version indicated by a trailing "+" on the name.  Perhaps that
would be better as a trailing "@" if we do (2) above.

4) James Manger suggested several changes to the syntax:

  a) remove the variable lists and instead have the processor
     maintain a memory of where it is in the URI generic syntax
     to know when to add the default ";" or "?" delimiters.
     Add a comma operator to support CSV expansions.

  b) change the default syntax to {var|default} instead of
     {var=default}, in order to allow ...

  c) define variable bindings within the template itself so
     that large schemas like OpenSearch can directly annotate
     every variable inside the template as opposed to annotating
     them by reference outside the template.  e.g.,

        find{?q=searchTerms}{?lang=language}

    I personally find (a) significantly uglier than the
    existing syntax;  (b) okay if people haven't implemented
    defaults yet; and, (c) a very slippery slope that, IMO, will
    result in the equivalent of WADL being embedded inside the
    template instead of remaining outside (where it can be safely
    ignored by RESTful applications).  YMMV.

I will be at the Anaheim IETF if anyone wants to discuss these
issues in person, but please send email to the list if you want
the discussion to result in changes to the next draft.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Begin forwarded message:

> From: [hidden email]
> Date: March 8, 2010 5:00:01 PM PST
> To: [hidden email]
> Subject: I-D Action:draft-gregorio-uritemplate-04.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
> Title           : URI Template
> Author(s)       : J. Gregorio, et al.
> Filename        : draft-gregorio-uritemplate-04.txt
> Pages           : 25
> Date            : 2010-03-08
>
> 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, along with guidelines for
> the use of URI Templates on the Internet.
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-04.txt



Reply | Threaded
Open this post in threaded view
|

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

Mike Burrows
Thanks, looks good.

I have a processor (in Python) that checks out ok for all the examples in section 1.2.  The only genuine special case in my code was the different treatment of empty values by the ; and ? operators.  I assume it's deliberate but I mention it just in case.

One trivial typo: a missing semicolon after path  := "/foo/bar" just before that same table in section 1.2.

Default values are there but untested; so far I parse but otherwise ignore prefix and suffix values.  I'll report back my progress on those later as a sanity check on the as-yet untested examples.

Re point 1 on error handling , it would be reasonable and indeed preferable in many languages for an implementation to raise an exception in the presence of errors, in which case the result string is undefined and any information about the error (or perhaps errors plural) would be returned back to the caller in the exception object.  That sort of behaviour is compatible with the spec as it stands but not with the kind of wording used below.  I would choose to leave the spec as it is.

FWIW, I'm with you Roy on point 4c.  My URI Templates are embedded in metadata that can annotate variables with as much flexibility as I'll ever need, and I imagine that this will be a fairly typical use case.  As for the other changes proposed in point 4 I'm not that fussed except that the novelty of tracking the standard across two language implementations is wearing a bit thin.  But if there's anything I can do to help...

Regards,
Mike
[hidden email]
http://positiveincline.com
http://twitter.com/asplake


On 10 March 2010 01:20, Roy T. Fielding <[hidden email]> wrote:
[second attempt to send this]

I managed to submit a new draft, just before the deadline,
with the obsolete sections removed and the sections that
still need writing marked as TBD.

The current issues (that I am aware of) include:

1) error handling -- as Joe noted, we can improve consistency
by making every error in the template result in a semi-expanded
result string and error indicator, rather than nulling
the result string and returning immediately.  My preference is
to copy bad expressions to the result, continue processing, and
indicate an error occurred to the caller.  This allows the
calling application to use the result string to point out
where the processing failed.

2) reserved substitution -- this is currently allowed only
by the "+" operator.  A suggestion by Mike Burrows is that the
"+" operator be changed into a variable name prefix so that
it can be selectively applied to any variable in any expression.
In addition to the added power, I found that a prefix would
simplify the value expansion description (and algorithm).
However, I have not made that change yet in 04.  Would such
a change be compatible with XRD and other applications?

3) I introduced explode modifiers, with the named variable
version indicated by a trailing "+" on the name.  Perhaps that
would be better as a trailing "@" if we do (2) above.

4) James Manger suggested several changes to the syntax:

 a) remove the variable lists and instead have the processor
    maintain a memory of where it is in the URI generic syntax
    to know when to add the default ";" or "?" delimiters.
    Add a comma operator to support CSV expansions.

 b) change the default syntax to {var|default} instead of
    {var=default}, in order to allow ...

 c) define variable bindings within the template itself so
    that large schemas like OpenSearch can directly annotate
    every variable inside the template as opposed to annotating
    them by reference outside the template.  e.g.,

       find{?q=searchTerms}{?lang=language}

   I personally find (a) significantly uglier than the
   existing syntax;  (b) okay if people haven't implemented
   defaults yet; and, (c) a very slippery slope that, IMO, will
   result in the equivalent of WADL being embedded inside the
   template instead of remaining outside (where it can be safely
   ignored by RESTful applications).  YMMV.

I will be at the Anaheim IETF if anyone wants to discuss these
issues in person, but please send email to the list if you want
the discussion to result in changes to the next draft.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Begin forwarded message:

> From: [hidden email]
> Date: March 8, 2010 5:00:01 PM PST
> To: [hidden email]
> Subject: I-D Action:draft-gregorio-uritemplate-04.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
>       Title           : URI Template
>       Author(s)       : J. Gregorio, et al.
>       Filename        : draft-gregorio-uritemplate-04.txt
>       Pages           : 25
>       Date            : 2010-03-08
>
> 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, along with guidelines for
> the use of URI Templates on the Internet.
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-04.txt




Reply | Threaded
Open this post in threaded view
|

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

Mike Burrows

Couple of issues with defaults.

This doesn't seem right:
    x{empty=_}y           xy

These
    x{;name=none}         x;name=Fred,Wilma,Pebbles
    x{?favs=none}         x?favs=color,red,volume,high
seem in conflict with
    {;list}               ;val1,val2,val3
    {;keys}               ;key1,val1,key2,val2

I suspect same too about
    x{;empty_list=none}   x;empty_list=none
    x{;empty_keys=none}   x;empty_keys=none

In both cases I may be missing something, but I wouldn't expect the presence of a default to change behaviour in this way.  Or is it the earlier part of the spec that is incorrect?

Regards,
Mike
[hidden email]
http://positiveincline.com
http://twitter.com/asplake


On 10 March 2010 15:18, Mike Burrows <[hidden email]> wrote:
Thanks, looks good.

I have a processor (in Python) that checks out ok for all the examples in section 1.2.  The only genuine special case in my code was the different treatment of empty values by the ; and ? operators.  I assume it's deliberate but I mention it just in case.

One trivial typo: a missing semicolon after path  := "/foo/bar" just before that same table in section 1.2.

Default values are there but untested; so far I parse but otherwise ignore prefix and suffix values.  I'll report back my progress on those later as a sanity check on the as-yet untested examples.

Re point 1 on error handling , it would be reasonable and indeed preferable in many languages for an implementation to raise an exception in the presence of errors, in which case the result string is undefined and any information about the error (or perhaps errors plural) would be returned back to the caller in the exception object.  That sort of behaviour is compatible with the spec as it stands but not with the kind of wording used below.  I would choose to leave the spec as it is.

FWIW, I'm with you Roy on point 4c.  My URI Templates are embedded in metadata that can annotate variables with as much flexibility as I'll ever need, and I imagine that this will be a fairly typical use case.  As for the other changes proposed in point 4 I'm not that fussed except that the novelty of tracking the standard across two language implementations is wearing a bit thin.  But if there's anything I can do to help...

Regards,
Mike
[hidden email]
http://positiveincline.com
http://twitter.com/asplake



On 10 March 2010 01:20, Roy T. Fielding <[hidden email]> wrote:
[second attempt to send this]

I managed to submit a new draft, just before the deadline,
with the obsolete sections removed and the sections that
still need writing marked as TBD.

The current issues (that I am aware of) include:

1) error handling -- as Joe noted, we can improve consistency
by making every error in the template result in a semi-expanded
result string and error indicator, rather than nulling
the result string and returning immediately.  My preference is
to copy bad expressions to the result, continue processing, and
indicate an error occurred to the caller.  This allows the
calling application to use the result string to point out
where the processing failed.

2) reserved substitution -- this is currently allowed only
by the "+" operator.  A suggestion by Mike Burrows is that the
"+" operator be changed into a variable name prefix so that
it can be selectively applied to any variable in any expression.
In addition to the added power, I found that a prefix would
simplify the value expansion description (and algorithm).
However, I have not made that change yet in 04.  Would such
a change be compatible with XRD and other applications?

3) I introduced explode modifiers, with the named variable
version indicated by a trailing "+" on the name.  Perhaps that
would be better as a trailing "@" if we do (2) above.

4) James Manger suggested several changes to the syntax:

 a) remove the variable lists and instead have the processor
    maintain a memory of where it is in the URI generic syntax
    to know when to add the default ";" or "?" delimiters.
    Add a comma operator to support CSV expansions.

 b) change the default syntax to {var|default} instead of
    {var=default}, in order to allow ...

 c) define variable bindings within the template itself so
    that large schemas like OpenSearch can directly annotate
    every variable inside the template as opposed to annotating
    them by reference outside the template.  e.g.,

       find{?q=searchTerms}{?lang=language}

   I personally find (a) significantly uglier than the
   existing syntax;  (b) okay if people haven't implemented
   defaults yet; and, (c) a very slippery slope that, IMO, will
   result in the equivalent of WADL being embedded inside the
   template instead of remaining outside (where it can be safely
   ignored by RESTful applications).  YMMV.

I will be at the Anaheim IETF if anyone wants to discuss these
issues in person, but please send email to the list if you want
the discussion to result in changes to the next draft.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Begin forwarded message:

> From: [hidden email]
> Date: March 8, 2010 5:00:01 PM PST
> To: [hidden email]
> Subject: I-D Action:draft-gregorio-uritemplate-04.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
>       Title           : URI Template
>       Author(s)       : J. Gregorio, et al.
>       Filename        : draft-gregorio-uritemplate-04.txt
>       Pages           : 25
>       Date            : 2010-03-08
>
> 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, along with guidelines for
> the use of URI Templates on the Internet.
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-04.txt





Reply | Threaded
Open this post in threaded view
|

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

Mike Burrows

Sorry ignore that first one, my mistake.  I'm still confused by the apparent conflicts though.


On 10 March 2010 16:18, Mike Burrows <[hidden email]> wrote:

Couple of issues with defaults.

This doesn't seem right:
    x{empty=_}y           xy

These
    x{;name=none}         x;name=Fred,Wilma,Pebbles
    x{?favs=none}         x?favs=color,red,volume,high
seem in conflict with
    {;list}               ;val1,val2,val3
    {;keys}               ;key1,val1,key2,val2

I suspect same too about
    x{;empty_list=none}   x;empty_list=none
    x{;empty_keys=none}   x;empty_keys=none

In both cases I may be missing something, but I wouldn't expect the presence of a default to change behaviour in this way.  Or is it the earlier part of the spec that is incorrect?
On 10 March 2010 15:18, Mike Burrows <[hidden email]> wrote:
Thanks, looks good.

I have a processor (in Python) that checks out ok for all the examples in section 1.2.  The only genuine special case in my code was the different treatment of empty values by the ; and ? operators.  I assume it's deliberate but I mention it just in case.

One trivial typo: a missing semicolon after path  := "/foo/bar" just before that same table in section 1.2.

Default values are there but untested; so far I parse but otherwise ignore prefix and suffix values.  I'll report back my progress on those later as a sanity check on the as-yet untested examples.

Re point 1 on error handling , it would be reasonable and indeed preferable in many languages for an implementation to raise an exception in the presence of errors, in which case the result string is undefined and any information about the error (or perhaps errors plural) would be returned back to the caller in the exception object.  That sort of behaviour is compatible with the spec as it stands but not with the kind of wording used below.  I would choose to leave the spec as it is.

FWIW, I'm with you Roy on point 4c.  My URI Templates are embedded in metadata that can annotate variables with as much flexibility as I'll ever need, and I imagine that this will be a fairly typical use case.  As for the other changes proposed in point 4 I'm not that fussed except that the novelty of tracking the standard across two language implementations is wearing a bit thin.  But if there's anything I can do to help...

Regards,
Mike
[hidden email]
http://positiveincline.com
http://twitter.com/asplake



On 10 March 2010 01:20, Roy T. Fielding <[hidden email]> wrote:
[second attempt to send this]

I managed to submit a new draft, just before the deadline,
with the obsolete sections removed and the sections that
still need writing marked as TBD.

The current issues (that I am aware of) include:

1) error handling -- as Joe noted, we can improve consistency
by making every error in the template result in a semi-expanded
result string and error indicator, rather than nulling
the result string and returning immediately.  My preference is
to copy bad expressions to the result, continue processing, and
indicate an error occurred to the caller.  This allows the
calling application to use the result string to point out
where the processing failed.

2) reserved substitution -- this is currently allowed only
by the "+" operator.  A suggestion by Mike Burrows is that the
"+" operator be changed into a variable name prefix so that
it can be selectively applied to any variable in any expression.
In addition to the added power, I found that a prefix would
simplify the value expansion description (and algorithm).
However, I have not made that change yet in 04.  Would such
a change be compatible with XRD and other applications?

3) I introduced explode modifiers, with the named variable
version indicated by a trailing "+" on the name.  Perhaps that
would be better as a trailing "@" if we do (2) above.

4) James Manger suggested several changes to the syntax:

 a) remove the variable lists and instead have the processor
    maintain a memory of where it is in the URI generic syntax
    to know when to add the default ";" or "?" delimiters.
    Add a comma operator to support CSV expansions.

 b) change the default syntax to {var|default} instead of
    {var=default}, in order to allow ...

 c) define variable bindings within the template itself so
    that large schemas like OpenSearch can directly annotate
    every variable inside the template as opposed to annotating
    them by reference outside the template.  e.g.,

       find{?q=searchTerms}{?lang=language}

   I personally find (a) significantly uglier than the
   existing syntax;  (b) okay if people haven't implemented
   defaults yet; and, (c) a very slippery slope that, IMO, will
   result in the equivalent of WADL being embedded inside the
   template instead of remaining outside (where it can be safely
   ignored by RESTful applications).  YMMV.

I will be at the Anaheim IETF if anyone wants to discuss these
issues in person, but please send email to the list if you want
the discussion to result in changes to the next draft.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Begin forwarded message:

> From: [hidden email]
> Date: March 8, 2010 5:00:01 PM PST
> To: [hidden email]
> Subject: I-D Action:draft-gregorio-uritemplate-04.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
>       Title           : URI Template
>       Author(s)       : J. Gregorio, et al.
>       Filename        : draft-gregorio-uritemplate-04.txt
>       Pages           : 25
>       Date            : 2010-03-08
>
> 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, along with guidelines for
> the use of URI Templates on the Internet.
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-04.txt






Reply | Threaded
Open this post in threaded view
|

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

Mike Burrows

Sorry again, that first one should have been
    x{empty_list=_}y           xy

which I can't easily reconcile with (for example)
    x{/empty_list=none}   x/none


On 10 March 2010 16:38, Mike Burrows <[hidden email]> wrote:

Sorry ignore that first one, my mistake.  I'm still confused by the apparent conflicts though.



On 10 March 2010 16:18, Mike Burrows <[hidden email]> wrote:

Couple of issues with defaults.

This doesn't seem right:
    x{empty=_}y           xy

These
    x{;name=none}         x;name=Fred,Wilma,Pebbles
    x{?favs=none}         x?favs=color,red,volume,high
seem in conflict with
    {;list}               ;val1,val2,val3
    {;keys}               ;key1,val1,key2,val2

I suspect same too about
    x{;empty_list=none}   x;empty_list=none
    x{;empty_keys=none}   x;empty_keys=none

In both cases I may be missing something, but I wouldn't expect the presence of a default to change behaviour in this way.  Or is it the earlier part of the spec that is incorrect?
On 10 March 2010 15:18, Mike Burrows <[hidden email]> wrote:
Thanks, looks good.

I have a processor (in Python) that checks out ok for all the examples in section 1.2.  The only genuine special case in my code was the different treatment of empty values by the ; and ? operators.  I assume it's deliberate but I mention it just in case.

One trivial typo: a missing semicolon after path  := "/foo/bar" just before that same table in section 1.2.

Default values are there but untested; so far I parse but otherwise ignore prefix and suffix values.  I'll report back my progress on those later as a sanity check on the as-yet untested examples.

Re point 1 on error handling , it would be reasonable and indeed preferable in many languages for an implementation to raise an exception in the presence of errors, in which case the result string is undefined and any information about the error (or perhaps errors plural) would be returned back to the caller in the exception object.  That sort of behaviour is compatible with the spec as it stands but not with the kind of wording used below.  I would choose to leave the spec as it is.

FWIW, I'm with you Roy on point 4c.  My URI Templates are embedded in metadata that can annotate variables with as much flexibility as I'll ever need, and I imagine that this will be a fairly typical use case.  As for the other changes proposed in point 4 I'm not that fussed except that the novelty of tracking the standard across two language implementations is wearing a bit thin.  But if there's anything I can do to help...

Regards,
Mike
[hidden email]
http://positiveincline.com
http://twitter.com/asplake



On 10 March 2010 01:20, Roy T. Fielding <[hidden email]> wrote:
[second attempt to send this]

I managed to submit a new draft, just before the deadline,
with the obsolete sections removed and the sections that
still need writing marked as TBD.

The current issues (that I am aware of) include:

1) error handling -- as Joe noted, we can improve consistency
by making every error in the template result in a semi-expanded
result string and error indicator, rather than nulling
the result string and returning immediately.  My preference is
to copy bad expressions to the result, continue processing, and
indicate an error occurred to the caller.  This allows the
calling application to use the result string to point out
where the processing failed.

2) reserved substitution -- this is currently allowed only
by the "+" operator.  A suggestion by Mike Burrows is that the
"+" operator be changed into a variable name prefix so that
it can be selectively applied to any variable in any expression.
In addition to the added power, I found that a prefix would
simplify the value expansion description (and algorithm).
However, I have not made that change yet in 04.  Would such
a change be compatible with XRD and other applications?

3) I introduced explode modifiers, with the named variable
version indicated by a trailing "+" on the name.  Perhaps that
would be better as a trailing "@" if we do (2) above.

4) James Manger suggested several changes to the syntax:

 a) remove the variable lists and instead have the processor
    maintain a memory of where it is in the URI generic syntax
    to know when to add the default ";" or "?" delimiters.
    Add a comma operator to support CSV expansions.

 b) change the default syntax to {var|default} instead of
    {var=default}, in order to allow ...

 c) define variable bindings within the template itself so
    that large schemas like OpenSearch can directly annotate
    every variable inside the template as opposed to annotating
    them by reference outside the template.  e.g.,

       find{?q=searchTerms}{?lang=language}

   I personally find (a) significantly uglier than the
   existing syntax;  (b) okay if people haven't implemented
   defaults yet; and, (c) a very slippery slope that, IMO, will
   result in the equivalent of WADL being embedded inside the
   template instead of remaining outside (where it can be safely
   ignored by RESTful applications).  YMMV.

I will be at the Anaheim IETF if anyone wants to discuss these
issues in person, but please send email to the list if you want
the discussion to result in changes to the next draft.

Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Begin forwarded message:

> From: [hidden email]
> Date: March 8, 2010 5:00:01 PM PST
> To: [hidden email]
> Subject: I-D Action:draft-gregorio-uritemplate-04.txt
> Reply-To: [hidden email]
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>
>       Title           : URI Template
>       Author(s)       : J. Gregorio, et al.
>       Filename        : draft-gregorio-uritemplate-04.txt
>       Pages           : 25
>       Date            : 2010-03-08
>
> 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, along with guidelines for
> the use of URI Templates on the Internet.
>
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-04.txt