Re: [apps-discuss] Question about json-home

[Erik Wilde <[e-mail]>]

hello darrel.

On 2014-02-17, 16:23 , Darrel Miller wrote:
> In section 3 of the json-home spec[1], it states,
>> Resource Objects MUST have exactly one of the "href" and "href-vars"
>> properties.
> My understanding of this is that a resource must either provide a URL
> in the href property or a URI Template in the href-template property.

yes, i do think that this is the current model. but please note that 
there is a later, but related draft on "Link Hints":

http://tools.ietf.org/html/draft-nottingham-link-hint

this one is strictly about URIs (i.e., not templates), and basically 
factors out the capability to represent information that might be 
helpful when following a link. since in some of the work we've been 
doing we need this capability to also cover URI templates, there's also 
a "Link Descriptions" draft, which supports URI templates:

http://tools.ietf.org/html/draft-wilde-link-desc

there's quite a bit of overlap between those two drafts, but the second 
one might be interesting in terms of combining URIs and URI templates.

> I recently ran into an issue where I had a deployed json-home document
> with a resource that had a href property and it was decided to add
> support for an optional query parameter to the URI. Unfortunately,
> there is no way to change the json-home document to support this
> optional query parameter without making a breaking change.

i think that's due to *two* reasons. one reason is that yes, you made a 
change and would like to make that change in the home document. but more 
importantly, you've moved from using URIs to using URI templates. it's 
kind of hard to imagine how you can make that latter change without 
breaking things, when you assume that before that change, everything was 
happily working without having to support URI templates.

> Is it really necessary to have both "href" and "href-template"?  Can
> the presence of href-vars not be used as an indicator of something
> being a template?

technically yes, but what you're doing then is to basically *only* 
support href-template (i.e., URI templates), and use the absence of 
variables to conclude that the template is one that does not contain any 
variables. which btw may not be what you should do, because there's no 
requirement that *all* variables in a template are described via href-vars.

at least in our cases, we might happily omit variables *in the 
description* where their semantics are static and captured by the link 
relation. we would then only serve variable descriptions for those 
variables where interesting things (such as value ranges) change at 
runtime, so that clients can see those changing runtime constraints.

> Is there some other way of supporting this evolution without having to
> introduce a new link relation type?

i don't think so, if you're really moving from a URI to a URI template. 
you could envision a design where you *only* use URI templates, and some 
of them happen to have no variables. then you could safely add a 
variable to such a template, but on the other hand, you would create a 
design where all clients must support URI templates, and not just URIs.

cheers,

dret.

-- 
erik wilde | mailto:[e-mail]  -  tel:[phone] |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |