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

From: Darrel Miller <[email-masked]>
Date: Mon, 17 Feb 2014 10:23:55 -0500

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.

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.

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?

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

Thanks,

Darrel

[1] http://tools.ietf.org/html/draft-nottingham-json-home-03#page-11

---

From: Erik Wilde <[email-masked]>
Date: Wed, 19 Feb 2014 10:28:45 +0100

hello darrel.

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

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

> the presence of href-vars not be used as an indicator of something

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.

> 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:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Erik Wilde <[email-masked]>
Date: Wed, 19 Feb 2014 11:05:44 +0100

hello darrel.

after thinking about this for a little while...

> design where all clients must support URI templates, and not just URIs.

...i guess i missed the obvious possibility to allow both a URI and a 
URI template. i don't know why the current model specifically disallows 
this, but i guess you could change the model to allow both. then you 
could safely add a template, and still leave the URI in there.

but in such a case, the link relation should probably say what to do in 
such a scenario: can clients freely choose between the URI and the 
template? or is the URI only for those clients not supporting templates?

and this is where it gets a bit tricky, because strictly speaking, link 
relations do not even apply to templates: RFC 5988 predates templates, 
and thus does not say anything about them. i guess it would be nice to 
either revise RFC 5988 to also talk about templates, or to have an 
additional RFC about "Templated Web Linking". but that may be a bit more 
work than what you were asking for ;-)

cheers,

dret.

---

From: Darrel Miller <[email-masked]>
Date: Wed, 19 Feb 2014 10:04:07 -0500

Erik,

Thanks for your feedback.

I am familiar with the link-hints spec.  My library for supporting
json-home[1] uses my Link implementation[2] which has support for
adding link hints.  I was not familiar with your link-desc spec.  I
will investigate further.

The scenario arose because we provided a link to a collection of items, e.g.

http://api.acme.com/orders/recent

The definition of the recent period was defined by the server.  A
request was made by a customer to enable them to define it.

http://api.acme.com/orders/recent{?days}

I see this evolution as a fairly normal one.  It seems somewhat
painful to have to mint a new extension link relation type to be able
to support this.

I see now that RFC 6570 states that,

> Distinct field, element, or attribute names should be used to
> differentiate protocol elements that carry a URI Template from those
> that expect a URI reference.

So that discourages attempting to re-use href to hold a template.

The current json-home spec explicitly prevents href and href-values
from existing at the same time.  If that were to change, then it would
be possible to have href and href-template at the same time.

There does seem to be some merit to having a "default" href for
clients that don't support templates and the more flexible template
URI.  And that would resolve my evolution problem.

Regarding the issue of link relations not being aware of URI
templates, my understanding of link relations seems to be much more
liberal than most peoples'.

>From RFC 5988
> a link relation type identifies the semantics of a link

and

>  Link relation types can also be used to indicate that the target
>  resource has particular attributes, or exhibits particular
>  behaviours; for example, a "service" link implies that the identified
>  resource is part of a defined protocol (in this case, a service
>  description).

I take this to mean, I can choose to define my link relation as
requiring template processing of a link's target URI.  Maybe I am
stretching the intent, but I have yet to be convinced of any negative
impacts that outweigh the benefits.

Regards,

Darrel

[1] https://github.com/tavis-software/Tavis.home
[2] https://github.com/tavis-software/Link

On Wed, Feb 19, 2014 at 5:05 AM, Erik Wilde <[email-masked]> wrote:
> ...i guess i missed the obvious possibility to allow both a URI and a URI
> template. i don't know why the current model specifically disallows this,
> but i guess you could change the model to allow both. then you could safely
> add a template, and still leave the URI in there.
>
> but in such a case, the link relation should probably say what to do in such
> a scenario: can clients freely choose between the URI and the template? or
> is the URI only for those clients not supporting templates?
>
> relations do not even apply to templates: RFC 5988 predates templates, and
> thus does not say anything about them. i guess it would be nice to either
> revise RFC 5988 to also talk about templates, or to have an additional RFC
> about "Templated Web Linking". but that may be a bit more work than what you
> were asking for ;-)
>
>
> cheers,
>
> dret.
>
> --
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Erik Wilde <[email-masked]>
Date: Wed, 19 Feb 2014 17:44:27 +0100

hello darrel.

> painful to have to mint a new extension link relation type to be able

that's true, but the main issue here seems to be that you're moving from 
a URI to a URI template, instead of moving from a URI template with no 
variables to one that has one. i see the first move as changing your 
interface, while the second move is much less problematic.

> So that discourages attempting to re-use href to hold a template.

yes, and i think the reason behind that is that URI templates need to be 
processed differently. so you cannot suddenly use a template in a place 
where you were using a URI before. it's a type error.

over time (if URI template use picks up), i would expect languages and 
frameworks to support both (think xs:URItemplate and XQuery/XSLT helper 
functions to process them), with a URI then simply being a special case 
of a URI template.

> be possible to have href and href-template at the same time.

yes. i am not quite sure why it prohibits using both at the same time. 
as long as it would also say what that would mean, that might solve your 
problem.

> URI.  And that would resolve my evolution problem.

yes. or, next time, you choose a design where you *always* use URI 
templates, and some of them simply have no variables. but that might 
annoy clients who now have to start understanding the URI template 
model, even if all they're ever using are plain URIs.

> liberal than most peoples'.  From RFC 5988

i did not want to say that it's a bad idea to use link relations for URI 
templates. and i think what you're trying to do makes a lot of sense and 
is the right way to go. all i wanted to say was that if URI templates 
become more common, it might be useful to have "Web Linking" that 
addresses how to use them explicitly.

cheers,

dret.