Structuring URI Templates

after musing about how to better combine URI Template Descriptions, mike amundsen responded rather fittingly with getting fancy, are we? while it may not be strictly required to make URI Templates composable via the description mechanism, it probably would be a nice capability to have.

as a scenario, take the example description from the current draft: the idea is to define some more advanced paging mechanism than just RFC5005-style links, and this idea very likely should be consistently used in services that are exposing various feeds. but in many cases, these feeds might have additional variables to specify, and then the question is how to best model, manage, and expose this.

the interesting question is whether this should and/or could be supported by Template Descriptions. let's assume that the paging model of feeds is as described in the example description (using pagesize and page variables).

one rather simple way to go would be the syntactic route. if somebody wanted to make this capability reusable, the template description for this would need to specify something along the lines of {pagesize,page}. unfortunately, URI Template expressions cannot be nested, which means that we cannot easily use this in a Template Description, add some linking concept across Template Descriptions, and then let a another URI Template say {?paging,color}, with the paging variable referring to the Template Description containing {pagesize,page}.

this problem could be avoided by using {?pagesize,page} in the paging template, and then using {paging}{&color} for the example given above, but this breaks down if we want to reuse two templates in another one: they would need to be defined in advance with either ? and &, which would make things rather brittle.

one possible solution to this problem would be to stick with {pagesize,page} as the reusable paging template, and add a processing rule that would say that if templates are referenced, and the included template is an expression (i.e., delimited by { and } with no other braces are in it), then the inclusion process strips those braces.

in this case, we could use {pagesize,page} as the paging template, and the example from above would use {?paging,page}, with paging being defined as an include variable. eliminating all XML fluff, we would end up with something like this for the paging template (let's call this paging.xml:

<td hreft="{pagesize,page}">
   <variable name="pagesize" concept-uri="http://example.com/feedpaging/pagesize"/>
   <variable name="page" concept-uri="http://example.com/feedpaging/page"/>
</td>

and then a template using this would look similar to this:

<td hreft="http://example.com/colorfeed{?paging,color}">
   <variable name="paging" template="paging.xml"/>
   <variable name="color" concept-uri="http://example.com/color"/>
</td>

there probably are many different ways in which this could be achieved, and one rather different approach would be to always reuse variables, instead of whole templates. that would change the dynamics of the mechanism, though, because in the above example, paging.xml could be updated with a third variable, and then all referencing descriptions would expose that additional variable without any need to change them.

the design presented here is mostly driven by the use cases we have for our internal designs so far, which revolve around an annoying number of variations of feeds, with a lot of concept reuse across them, and currently no ability to manage this without copious copy/paste, which always is a bad sign. i'd be very interested to hear about other use cases in services that use URI Templates, and whether they have invented their own reusability concepts, or might be able to use the design presented here (or a variation of it).

Templates Descriptions are a -00 draft and there are several open issues, and the problem described here has only made it into the open issues section for -01. anybody using URI Templates, please share your experience with how you're managing this currently, and whether something similar to the design presented here might be able to make this management problem easier. thanks!

Comments

[5 Template Responsive]

Previous I Want Thanking the author for giving knowledge about the URI Template. I do not have experience when arranging URI Template, because this is the first time I learned to organize URI Template.