URI Template experience

[Joe Gregorio-2]

It's been a while since the URI Template draft has been updated, and
in the interim
there has been some implementation experience:

   http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/
   http://code.google.com/p/uri-templates/wiki/Implementations

In the intervening months two things have happened:

1. In all the URI Template examples I've seen, only the simplest case {foo} has
   even been shown.

2. I've been repeatedly asked about "going the other way", i.e. parsing URIs
   based on templates.

This leads to two questions:

1. Are there any real-world uses of the more complex URI Templates, or
is {foo} enough?

2. *If* the syntax is simplified to {foo} there is an opportunity to
support the parsing
   case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
    Is that of interest to anyone?

  Thanks,
  -joe

--
Joe Gregorio        http://bitworking.org

[Marc Hadley]

On May 18, 2009, at 3:25 PM, Joe Gregorio wrote:
>
> 2. *If* the syntax is simplified to {foo} there is an opportunity to
> support the parsing
>   case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
>    Is that of interest to anyone?
>
In Java land JAX-RS supports use of the simplified syntax for  
dispatching incoming requests, see:

https://jsr311.dev.java.net/nonav/releases/1.0/spec/ 
spec3.html#x3-300003.4

and

https://jsr311.dev.java.net/nonav/releases/1.0/javax/ws/rs/Path.html

Most examples I've seen use the simplified syntax but several have  
used the extended regex syntax to satisfy more complex requirements.

Marc.

[Roy T. Fielding]

On May 18, 2009, at 12:25 PM, Joe Gregorio wrote:

> It's been a while since the URI Template draft has been updated, and
> in the interim
> there has been some implementation experience:
>
>    http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/
>    http://code.google.com/p/uri-templates/wiki/Implementations
>
> In the intervening months two things have happened:
>
> 1. In all the URI Template examples I've seen, only the simplest  
> case {foo} has
>    even been shown.
>
> 2. I've been repeatedly asked about "going the other way", i.e.  
> parsing URIs
>    based on templates.
>
> This leads to two questions:
>
> 1. Are there any real-world uses of the more complex URI Templates, or
> is {foo} enough?
>
> 2. *If* the syntax is simplified to {foo} there is an opportunity to
> support the parsing
>    case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
>     Is that of interest to anyone?

Hi Joe,

Your question implies that the features in the current draft are
somehow dependent on the extent to which the current draft has
been implemented in the wild.  I think that is backwards, since
the draft received many comments and did not change as a result.
For example,

http://www.w3.org/mid/07109D44-233D-42F3-ACB0-56B4A6562903@...

So, the answer to your question is that implementors are patiently
waiting (perhaps too patiently) for the draft to be updated.
Would it help if I issued a draft with the alternative syntax?

....Roy

[Robert Brewer-4]

Roy T. Fielding wrote:
> On May 18, 2009, at 12:25 PM, Joe Gregorio wrote:
>
>> It's been a while since the URI Template draft has been updated, and
>> in the interim
>> there has been some implementation experience:
>>
>>    http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/
>>    http://code.google.com/p/uri-templates/wiki/Implementations
>>
>> In the intervening months two things have happened:
>>
>> 1. In all the URI Template examples I've seen, only the simplest case
>> {foo} has
>>    even been shown.
>>
>> 2. I've been repeatedly asked about "going the other way", i.e.
>> parsing URIs
>>    based on templates.
>>
>> This leads to two questions:
>>
>> 1. Are there any real-world uses of the more complex URI Templates, or
>> is {foo} enough?
>>
>> 2. *If* the syntax is simplified to {foo} there is an opportunity to
>> support the parsing
>>    case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
>>     Is that of interest to anyone?
>
> Hi Joe,
>
> Your question implies that the features in the current draft are
> somehow dependent on the extent to which the current draft has
> been implemented in the wild.  I think that is backwards, since
> the draft received many comments and did not change as a result.
> For example,
>
> http://www.w3.org/mid/07109D44-233D-42F3-ACB0-56B4A6562903@...


Much of which I stole and stuck into
http://www.aminus.org/rbre/shoji/shoji-draft-01.txt, which is being used
to run http://parachutes.org/api/browser for one. Why not push ahead
with that? Given the dearth of complexity in implementations of URI
Templates, I'd much prefer the simpler syntax you proposed there. Make
it simple enough, and regexes for dispatching on the server fall out
quite nicely.


Robert Brewer
fumanchu@...

[jlouvel]

Some parts of this message have been removed. Learn more about Nabble's security policy.

Hi all,

 

It would useful to restructure the draft to separate the minimal syntax that would be mandatory to support and that would work both on client-side and server-side.

 

Then, we could add an optional part defining a more extensive syntax, suitable for client-side usage. I also suspect, that a third part defining extension for server-side URI templates would be useful.

 

Our experience so far with Restlet is that the simpler syntax is sufficient for most cases. When customization of what a variable should match is needed, we handle that via the Java API and people seem quite happy with that:

http://www.restlet.org/documentation/snapshot/api/org/restlet/util/Template.html

 

Best regards,
Jerome Louvel
--
Restlet ~ Founder and Lead developer ~ http://www.restlet.org
Noelios Technologies ~ Co-founder ~ http://www.noelios.com

 

 

 

 

De : uri-request@... [mailto:uri-request@...] De la part de Robert Brewer
Envoyé : mardi 19 mai 2009 05:10
À : Roy T. Fielding
Cc : Joe Gregorio; URI
Objet : Re: URI Template experience

 

Roy T. Fielding wrote:
> On May 18, 2009, at 12:25 PM, Joe Gregorio wrote:
>
>> It's been a while since the URI Template draft has been updated, and
>> in the interim
>> there has been some implementation experience:
>>
>>    http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/
>>    http://code.google.com/p/uri-templates/wiki/Implementations
>>
>> In the intervening months two things have happened:
>>
>> 1. In all the URI Template examples I've seen, only the simplest case
>> {foo} has
>>    even been shown.
>>
>> 2. I've been repeatedly asked about "going the other way", i.e.
>> parsing URIs
>>    based on templates.
>>
>> This leads to two questions:
>>
>> 1. Are there any real-world uses of the more complex URI Templates, or
>> is {foo} enough?
>>
>> 2. *If* the syntax is simplified to {foo} there is an opportunity to
>> support the parsing
>>    case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
>>     Is that of interest to anyone?
>
> Hi Joe,
>
> Your question implies that the features in the current draft are
> somehow dependent on the extent to which the current draft has
> been implemented in the wild.  I think that is backwards, since
> the draft received many comments and did not change as a result.
> For example,
>
> http://www.w3.org/mid/07109D44-233D-42F3-ACB0-56B4A6562903@...


Much of which I stole and stuck into
http://www.aminus.org/rbre/shoji/shoji-draft-01.txt, which is being used
to run http://parachutes.org/api/browser for one. Why not push ahead
with that? Given the dearth of complexity in implementations of URI
Templates, I'd much prefer the simpler syntax you proposed there. Make
it simple enough, and regexes for dispatching on the server fall out
quite nicely.


Robert Brewer
fumanchu@...

[Mike Burrows]

[I'm not a member of this list - I'm responding to Joe's blog post, so apologies if this message doesn't thread properly]

I used URI Templates in a proof-of-concept that demonstrated scripting (in Ruby) and acceptance testing of a real-time Java-based component in the bond trading arena that previously had no HTTP interface.  I'm no longer with the firm, but the project was regarded as a success (others are building on it), and the idea of resource-oriented HTTP interfaces also gained traction internally.  Now on leave, I have built on the experience to prototype a metadata-driven Rubygem path-to, and then described_routes, which generates said data from Rails in JSON, YAML and XML.  I'm aware of one real-world Javascript client for the JSON data.

Ruby has excellent URI template support in the shape of Bob Aman's (sporkmonger's) addressable gem.  I've taken advantage of a recent feature which allows templates to be partially expanded, which in my case allows the generation of metadata specific to a resource instance, which in turn points the way to discovery via arbitrary landing sites, not just the application's root or some designated metadata link.  I find this interesting as it may offer convenient ways for client applications to find and follow hyperlinks that relate to arbitrary non-html-based representations.

I do use the prefix and join operators.  For example, typical Rails routes translate to paths like

   /parent/{parent_id}{-prefix|.|format}

   /parent/{parent_id}/child{-prefix|.|format}

where {format} is an optional parameter.  The {format} parameter makes it difficult to model this nicely in schemes that are strictly hierarchical and (more generally) there's merit I think in the indirection offered by having full URI templates.  I have argued that this reduces coupling.

The join operator is useful when modelling APIs that rely heavily on query parameters (e.g. Delicious).  I like being able to disregard whether a parameter goes into the path or the query.

A lot of this is covered in Partial template expansion in described_routes (including the comments) and Manifesto and roadmaps for described_routes and path-to.  The whole 3-4 week journey is covered extensively in earlier posts.

My conclusion therefore is to keep the more advanced features of URI Templates.  The examples (if they're intended as a test set) could do with beefing up - I contributed a couple of bug fixes to Addressable that weren't covered by them.  I did express regrets early on that URI templates didn't distinguish between optional and mandatory parameters, but I've dealt with that now in the surrounding metadata and it's no longer a concern.

I'm not interested personally in parsing.  Decent web frameworks do it already, and if clients need to do it there's probably something wrong somewhere. 

Regards,

Mike

mjb@...

http://positiveincline.com

http://twitter.com/asplake

It's been a while since the URI Template draft has been updated, and

in the interim

there has been some implementation experience:

   http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/

   http://code.google.com/p/uri-templates/wiki/Implementations

In the intervening months two things have happened:

1. In all the URI Template examples I've seen, only the simplest case {foo} has

   even been shown.

2. I've been repeatedly asked about "going the other way", i.e. parsing URIs

   based on templates.

This leads to two questions:

1. Are there any real-world uses of the more complex URI Templates, or

is {foo} enough?

2. *If* the syntax is simplified to {foo} there is an opportunity to

support the parsing

   case, ala http://bitworking.org/projects/1812/wsgidispatcher.html

    Is that of interest to anyone?

  Thanks,

  -joe

-- 

Joe Gregorio        http://bitworking.org

[Aristotle Pagaltzis]

Hi Joe,

I always thought the proposed syntax was too complex: it caters
to very unlikely use cases at the cost of high cognitive overhead
in common ones. I suspect this is the reason that the more
powerful features have not seen any adoption.

So I signed up to propose a much simplified syntax, but I see Roy
had previously already made much the same proposal in
http://www.w3.org/mid/07109D44-233D-42F3-ACB0-56B4A6562903@...

I had in mind some further simplifications, though. Mainly, I
would like the output of expansions to be more invariant so that
it’s easier to use mixed static and interpolated query strings.

Specifically, I would suggest the same syntax as Roy, but with an
expansion operator `&` instead of `?`, which never produces a
leading question mark itself. Then I would declare bare `?`, `&`,
and `;` (outside of expansions) primary operators (like `{}`),
whose trivial effect is to output themselves – unless they’d end
up as the last character in the expanded URI, in which case they
produce *no* output. (Of course if several such optional
characters bunch up at the end, they’re *all* dropped.)

So a template for a typical query URI would be written something
like

    /articles?{&tag,per_page,q}

which would just Do The Right Thing. If needs later changed and
you wanted to include a static parameter, it might become eg.

    /articles?style=summary&{&tag,per_page,q}

and would still DTRT.

I find that having those URI meta characters be look like part of
the static template makes for a more readable syntax, and in this
way the writer also doesn’t need to pay such close attention to
the ordering of components in a template while the implementation
can provide this flexibility with very little conditional logic.

While this proposal means a small increase in conceptual
entities, I believe the result significantly benefits both
language implementors and language users. If you were to try
to cram these smarts into the expansion operators, the
implementation would have to keep track of the same state to
implement them as in my proposal, but it would be much trickier
to get right, and template writers would still be forced to pay
attention to the ordering of static parts vs expansions.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Mike Burrows]

References (the archive doesn't show the links):

1. path-to: http://github.com/asplake/path-to/tree
2. described_routes: http://github.com/asplake/described_routes/tree
3. addressable: http://github.com/asplake/addressable/tree
4. Partial template expansion in described_routes: http://positiveincline.com/?p=294
5. Manifesto and roadmaps for described_routes and path-to: http://positiveincline.com/?p=213

Also a very noddy Delicious example here: http://positiveincline.com/?p=254, slightly improved upon here from a Ruby perspective thanks to positional parameters here: http://positiveincline.com/?p=285.

Regards,
Mike

2009/5/19 Michael Burrows <asplake@...>

[I'm not a member of this list - I'm responding to Joe's blog post, so apologies if this message doesn't thread properly]

I used URI Templates in a proof-of-concept that demonstrated scripting (in Ruby) and acceptance testing of a real-time Java-based component in the bond trading arena that previously had no HTTP interface.  I'm no longer with the firm, but the project was regarded as a success (others are building on it), and the idea of resource-oriented HTTP interfaces also gained traction internally.  Now on leave, I have built on the experience to prototype a metadata-driven Rubygem path-to, and then described_routes, which generates said data from Rails in JSON, YAML and XML.  I'm aware of one real-world Javascript client for the JSON data.

Ruby has excellent URI template support in the shape of Bob Aman's (sporkmonger's) addressable gem.  I've taken advantage of a recent feature which allows templates to be partially expanded, which in my case allows the generation of metadata specific to a resource instance, which in turn points the way to discovery via arbitrary landing sites, not just the application's root or some designated metadata link.  I find this interesting as it may offer convenient ways for client applications to find and follow hyperlinks that relate to arbitrary non-html-based representations.

I do use the prefix and join operators.  For example, typical Rails routes translate to paths like

   /parent/{parent_id}{-prefix|.|format}

   /parent/{parent_id}/child{-prefix|.|format}

where {format} is an optional parameter.  The {format} parameter makes it difficult to model this nicely in schemes that are strictly hierarchical and (more generally) there's merit I think in the indirection offered by having full URI templates.  I have argued that this reduces coupling.

The join operator is useful when modelling APIs that rely heavily on query parameters (e.g. Delicious).  I like being able to disregard whether a parameter goes into the path or the query.

A lot of this is covered in Partial template expansion in described_routes (including the comments) and Manifesto and roadmaps for described_routes and path-to.  The whole 3-4 week journey is covered extensively in earlier posts.

My conclusion therefore is to keep the more advanced features of URI Templates.  The examples (if they're intended as a test set) could do with beefing up - I contributed a couple of bug fixes to Addressable that weren't covered by them.  I did express regrets early on that URI templates didn't distinguish between optional and mandatory parameters, but I've dealt with that now in the surrounding metadata and it's no longer a concern.

I'm not interested personally in parsing.  Decent web frameworks do it already, and if clients need to do it there's probably something wrong somewhere. 

Regards,

Mike

mjb@...

http://positiveincline.com

http://twitter.com/asplake

It's been a while since the URI Template draft has been updated, and

in the interim

there has been some implementation experience:

   http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/

   http://code.google.com/p/uri-templates/wiki/Implementations

In the intervening months two things have happened:

1. In all the URI Template examples I've seen, only the simplest case {foo} has

   even been shown.

2. I've been repeatedly asked about "going the other way", i.e. parsing URIs

   based on templates.

This leads to two questions:

1. Are there any real-world uses of the more complex URI Templates, or

is {foo} enough?

2. *If* the syntax is simplified to {foo} there is an opportunity to

support the parsing

   case, ala http://bitworking.org/projects/1812/wsgidispatcher.html

    Is that of interest to anyone?

  Thanks,

  -joe

-- 

Joe Gregorio        http://bitworking.org

[Mike Burrows]

Hi Aristotle,

The complexity is only an issue while there is a lack of good library implementations across languages.  I'm happy that Ruby has a really good one (in addressable); I suspect that what's holding others back (it had that effect on me for a while) is the uncertain status of URI Templates as a standard.

As I said in my earlier post, the prefix and join operators are useful, but that's not so say that the syntax couldn't be improved - in fact I once bemoaned the inability to distinguish mandatory parameters, though the prefix operator kinda means the latter to me now.  That said, a change of syntax would for me mean merely plugging in an alternate or upgraded library; I suggest that this is what we all need to be aiming for.  Encapsulate!

Regards,
Mike

mjb@...

http://positiveincline.com

http://twitter.com/asplake

2009/5/19 Aristotle Pagaltzis <pagaltzis@...>

Hi Joe,

I always thought the proposed syntax was too complex: it caters
to very unlikely use cases at the cost of high cognitive overhead
in common ones. I suspect this is the reason that the more
powerful features have not seen any adoption.

So I signed up to propose a much simplified syntax, but I see Roy
had previously already made much the same proposal in

http://www.w3.org/mid/07109D44-233D-42F3-ACB0-56B4A6562903@...

I had in mind some further simplifications, though. Mainly, I
would like the output of expansions to be more invariant so that
it’s easier to use mixed static and interpolated query strings.

Specifically, I would suggest the same syntax as Roy, but with an
expansion operator `&` instead of `?`, which never produces a
leading question mark itself. Then I would declare bare `?`, `&`,
and `;` (outside of expansions) primary operators (like `{}`),
whose trivial effect is to output themselves – unless they’d end
up as the last character in the expanded URI, in which case they
produce *no* output. (Of course if several such optional
characters bunch up at the end, they’re *all* dropped.)

So a template for a typical query URI would be written something
like

   /articles?{&tag,per_page,q}

which would just Do The Right Thing. If needs later changed and
you wanted to include a static parameter, it might become eg.

   /articles?style=summary&{&tag,per_page,q}

and would still DTRT.

I find that having those URI meta characters be look like part of
the static template makes for a more readable syntax, and in this
way the writer also doesn’t need to pay such close attention to
the ordering of components in a template while the implementation
can provide this flexibility with very little conditional logic.

While this proposal means a small increase in conceptual
entities, I believe the result significantly benefits both
language implementors and language users. If you were to try
to cram these smarts into the expansion operators, the
implementation would have to keep track of the same state to
implement them as in my proposal, but it would be much trickier
to get right, and template writers would still be forced to pay
attention to the ordering of static parts vs expansions.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Aristotle Pagaltzis]

* Michael Burrows <asplake@...> [2009-05-19 12:35]:
> The complexity is only an issue while there is a lack of good
> library implementations across languages.

Complexity is *always* an issue. Sweeping it under the library
rug is a mistake. Less code is *always* better, no matter how
limited the scale we are talking about. Even if users don’t
implement URI Templates themselves, they are still better off by
having smaller libraries available, and are empowered by having
the option of cheaply implementing one themselves. And in this
case, there isn’t even a trade-off to consider; the increased
simplicity actually yields a better solution by every other
metric as well, to my mind anyway.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Sporkmonger]

> Ruby has excellent URI template support in the shape of Bob Aman's (sporkmonger's) addressable gem.

Thanks.  :-)

> My conclusion therefore is to keep the more advanced features of URI Templates.  The examples (if they're intended as a test set) could do with beefing up - I contributed a couple of bug fixes to Addressable that weren't covered by them.  I did express regrets early on that URI templates didn't distinguish between optional and mandatory parameters, but I've dealt with that now in the surrounding metadata and it's no longer a concern.

I'm with Michael here.  Please keep the advanced features.  Just
because they only get used by a handful of people doesn't mean they're
not useful.  I suspect they're less used for a variety of reasons,
through no fault of the URI template spec.

Couple of factors:
* They're obviously harder to handle than the {foo} case for anyone
who's rolling their own URI template support.  This will be less of an
issue as library support improves.
* Frameworks and application developers have been moving towards
representing parameters like so: /{controller}/{action}/{id}/  Some
people even have gotten the impression that "pretty" URIs are what
REST is all about.  There is a non-trivial number of people who think
the presence of a query parameter is inherently unRESTful.  With this
kind of misunderstanding, it's not unreasonable to expect that the
{foo} case will continue to be dominant in the real world for quite
some time.
* URI templates for routing are only just starting to catch on.  I
just submitted a [small patch][1] (which was accepted) to the Sinatra
web framework that allows URI templates to be used for routing
purposes.  IMHO, the advanced features of URI templates are much more
useful in this scenario.  Well, aside from the neg and opt operators
anyways.  Right now my library throws an exception if you try to use
them in a route because you can't extract a canonical value for the
parameter.  (Note that neg and opt are still useful for simplifying
partial template expansion.)

I've put a HUGE amount of work into the Addressable library, and if
you haven't played with it yet and you're interested in my take on
what URI templates can be used for, you may want to take it for a
spin, even if you're not a Rubyist.

> 1. Are there any real-world uses of the more complex URI Templates, or
> is {foo} enough?

I can say, unequivocally, yes.  My current employer is making
extensive use of them for an internal application.  We have to
maintain several UIs to our application, including a Flex one.  We
send URI templates to the Flex UI so that it knows how to get the
right data out of our REST interfaces.  Sometimes a template needs to
get partially filled in before being passed to Flex, which was the
motivation for the partial evaluation algorithm.  (Essentially,
Template + Mapping -> Template instead of Template + Mapping -> URI.)

> 2. *If* the syntax is simplified to {foo} there is an opportunity to
> support the parsing
>    case, ala http://bitworking.org/projects/1812/wsgidispatcher.html
>     Is that of interest to anyone?

Yes, that's of interest, however, simplification is not really
necessary to support this use case.  See Addressable::Template.match.
:-)

I would be very interested, however, in seeing the reverse operation
of each operator actually specified.  Especially neg/opt, since it
bothers me to have to throw those exceptions due to undefined
behavior.

I should probably note that a lot of the improvements I've made to
Addressable are still only available via source control.  So if you're
going to take a look, you want to grab a copy off of [GitHub][2].  The
test suite may also be of interest.  It's rather extensive.

Bob Aman

[1]: https://sinatra.lighthouseapp.com/projects/9779-sinatra/tickets/217
[2]: http://github.com/sporkmonger/addressable/tree/master

[Sporkmonger]

> I suspect they're less used for a variety of reasons,
> through no fault of the URI template spec.

I think someone bcc'ed me into this conversation, so I'm only just now
getting a chance to read through the rest of the thread.  I guess I'd
add that I'm with Roy and everyone else who's asking for a
simplification of the syntax.  I need the advanced functionality of
the templates, but I certainly would not object to getting that
functionality in a less complicated package.  I like where Roy was
headed with his syntax changes.  I never really liked the
{operator|argument|params} syntax, and I'd love to be able to use
something simpler.

> It would useful to restructure the draft to separate the minimal syntax that would be mandatory to support and that would work both on client-side and server-side.
>
> Then, we could add an optional part defining a more extensive syntax, suitable for client-side usage. I also suspect, that a third part defining extension for server-side URI templates would be useful.

I don't think I like that idea.  I would greatly prefer one syntax for
usage everywhere.  If the syntax, as-is, is too complex to work with
on one side or the other, then we need to fix it until it IS useful
everywhere.

Bob Aman

[Sporkmonger]

> Specifically, I would suggest the same syntax as Roy, but with an
> expansion operator `&` instead of `?`, which never produces a
> leading question mark itself. Then I would declare bare `?`, `&`,
> and `;` (outside of expansions) primary operators (like `{}`),
> whose trivial effect is to output themselves – unless they’d end
> up as the last character in the expanded URI, in which case they
> produce *no* output. (Of course if several such optional
> characters bunch up at the end, they’re *all* dropped.)

I really like the idea of never having to worry about the case of:

/path/to/something?

+1

Bob Aman

[Aristotle Pagaltzis]

* Bob Aman <bob@...> [2009-05-19 21:35]:

> > It would useful to restructure the draft to separate the
> > minimal syntax that would be mandatory to support and that
> > would work both on client-side and server-side.
> >
> > Then, we could add an optional part defining a more extensive
> > syntax, suitable for client-side usage. I also suspect, that
> > a third part defining extension for server-side URI templates
> > would be useful.
>
> I don't think I like that idea.

Me either.

> I would greatly prefer one syntax for usage everywhere. If the
> syntax, as-is, is too complex to work with on one side or the
> other, then we need to fix it until it IS useful everywhere.

Agreed. The less variance, the better. For something that might,
among other things, basically supplant `<form>` for programmatic
clients on the web, with the implied breadth of adoption, the #1
goal should be relentless simplicity.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[John Cowan]

Aristotle Pagaltzis scripsit:

> Agreed. The less variance, the better. For something that might,
> among other things, basically supplant `<form>` for programmatic
> clients on the web, with the implied breadth of adoption, the #1
> goal should be relentless simplicity.

Simplicity itself is not a sensible goal.  Simplicity *for a given
amount of function* is a sensible goal.  A language in which the only
possible program is a hello-world one will be a very simple language,
but it doesn't provide much function.

URIs themselves aren't very simple at all, but they're about as simple
as they can be for the specified amount of function (protocol, host,
arbitrary hierarchical information path, arbitrary non-hierarchical
parameters).  It would simplify them, for example, to exclude %-escaping,
but only by sacrificing important function.

Specifically, template generation is more general than parsing, because
it goes from rich information to a wire protocol.  Supporting only the
parseable subset of templates means that important generation function
must be abandoned.

--
John Cowan  cowan@...  http://ccil.org/~cowan
Female celebrity stalker, on a hot morning in Cairo:
"Imagine, Colonel Lawrence, ninety-two already!"
El Auruns's reply:  "Many happy returns of the day!"

[Roy T. Fielding]

On May 19, 2009, at 1:57 AM, Aristotle Pagaltzis wrote:

> I had in mind some further simplifications, though. Mainly, I
> would like the output of expansions to be more invariant so that
> it’s easier to use mixed static and interpolated query strings.
>
> Specifically, I would suggest the same syntax as Roy, but with an
> expansion operator `&` instead of `?`, which never produces a
> leading question mark itself. Then I would declare bare `?`, `&`,
> and `;` (outside of expansions) primary operators (like `{}`),
> whose trivial effect is to output themselves – unless they’d end
> up as the last character in the expanded URI, in which case they
> produce *no* output. (Of course if several such optional
> characters bunch up at the end, they’re *all* dropped.)

I think that violates a very basic principle of templates --
that whatever is outside the delimiters always be interpreted
as static text.  It implies that the delimiter be changed from
one-character that is never allowed in URI to two characters,
the first of which will occur in most URI, changing the algorithm
from zero-lookahead to one-lookahead.  Big -1.

> So a template for a typical query URI would be written something
> like
>
>     /articles?{&tag,per_page,q}
>
> which would just Do The Right Thing. If needs later changed and
> you wanted to include a static parameter, it might become eg.
>
>     /articles?style=summary&{&tag,per_page,q}
>
> and would still DTRT.

But it would not describe the common case in way that is
reversible, and doesn't account for the style=summary being
in an *unordered* query part.

....Roy

[jlouvel]

+1

For example, when you parse you might want to match again several
alternative patterns. This isn't a choice you want to have when formatting
an URI based on a URI template. I'm sure there are other cases, where the
syntax might differ. Of course, the core syntax should stay consistent.

Best regards,
Jerome Louvel
--
Restlet ~ Founder and Lead developer ~ http://www.restlet.org
Noelios Technologies ~ Co-founder ~ http://www.noelios.com



-----Message d'origine-----
De : uri-request@... [mailto:uri-request@...] De la part de John Cowan
Envoyé : mardi 19 mai 2009 22:34
À : Aristotle Pagaltzis
Cc : uri@...
Objet : Re: URI Template experience

Aristotle Pagaltzis scripsit:

> Agreed. The less variance, the better. For something that might,
> among other things, basically supplant `<form>` for programmatic
> clients on the web, with the implied breadth of adoption, the #1
> goal should be relentless simplicity.

Simplicity itself is not a sensible goal.  Simplicity *for a given
amount of function* is a sensible goal.  A language in which the only
possible program is a hello-world one will be a very simple language,
but it doesn't provide much function.

URIs themselves aren't very simple at all, but they're about as simple
as they can be for the specified amount of function (protocol, host,
arbitrary hierarchical information path, arbitrary non-hierarchical
parameters).  It would simplify them, for example, to exclude %-escaping,
but only by sacrificing important function.

Specifically, template generation is more general than parsing, because
it goes from rich information to a wire protocol.  Supporting only the
parseable subset of templates means that important generation function
must be abandoned.

--
John Cowan  cowan@...  http://ccil.org/~cowan
Female celebrity stalker, on a hot morning in Cairo:
"Imagine, Colonel Lawrence, ninety-two already!"
El Auruns's reply:  "Many happy returns of the day!"

[Aristotle Pagaltzis]

* Roy T. Fielding <fielding@...> [2009-05-19 23:20]:

> On May 19, 2009, at 1:57 AM, Aristotle Pagaltzis wrote:
>> So a template for a typical query URI would be written
>> something like
>>
>>     /articles?{&tag,per_page,q}
>>
>> which would just Do The Right Thing. If needs later changed
>> and you wanted to include a static parameter, it might become
>> eg.
>>
>>     /articles?style=summary&{&tag,per_page,q}
>>
>> and would still DTRT.
>
> But it would not describe the common case in way that is
> reversible, and doesn't account for the style=summary being
> in an *unordered* query part.

So how do you do that? As far as I can tell, neither do any other
proposed syntaxes.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Aristotle Pagaltzis]

* John Cowan <cowan@...> [2009-05-19 23:35]:
> Simplicity itself is not a sensible goal. Simplicity *for a
> given amount of function* is a sensible goal. A language in
> which the only possible program is a hello-world one will be a
> very simple language, but it doesn't provide much function.

You cannot treat simplicity and functionality as separate in
design. The amount of functionality worth having is co-determined
by the complexity of the result; the degree of simplicity worth
aiming for is co-determined by the usefulness of the result.

> Specifically, template generation is more general than parsing,
> because it goes from rich information to a wire protocol.
> Supporting only the parseable subset of templates means that
> important generation function must be abandoned.

The availability or rich information is precisely the point.
Processing instructions can be included in this rich data in
any number of forms, be that through different API calls for
declaring variables, by passing the template as part of a
data structure with hints, or whatever. At generation time,
all options are open.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Mike Schinkel-5]

On May 19, 2009, at 11:08 PM, Aristotle Pagaltzis wrote:

> You cannot treat simplicity and functionality as separate in
> design. The amount of functionality worth having is co-determined
> by the complexity of the result; the degree of simplicity worth
> aiming for is co-determined by the usefulness of the result.

Agreed. Adoption correlates strongly with simplicity. Look at the  
original HTML; it was simple and didn't handle many use cases well  
(still doesn't) but it was 10,000 times better than a "standard" that  
never reaches recommendation stage and hence rarely ever gets used.

Keep it very simple, solve the 80 percentile case and then address the  
remaining 20% over the next two decades (a.l.a. HTML4 vs HTML5.)

JMTCW.

-Mike Schinkel