The _links element semantics

[oyvindfanebust]

I really like what you are doing with hyper+json! There is one tiny thing that bugs me about the semantics though. You use the _links element for both links and forms. I can understand that you want to be as terse as possible, but is a form really a link? I would suggest either splitting it into _forms and _links or renaming it to something like _controls (as in hypermedia control).

[cainus]

Thanks for the feedback... I actually had them separate at one point ( with _forms, like you said ), but there were a few things that struck me as wrong about that:

• There's not really an advantage to separating state-changing operations from read operations as far as I can tell. eg: { _ links : { ...}, _forms : { ... }}
• A form is a gui "control", and since hyper+json has no gui elements it doesn't really make much sense to use that term. I don't really mind your _controls idea (maybe that's a better name?), but if I were to use that, I think the read-only controls (links) should go in the same place, no? Again, I don't see a need for two buckets of "controls" with a separation based on whether they change state or not, since the method attribute is all the distinction you need.

What do you think?

[oyvindfanebust]

I agree that one "bucket" should be sufficient, though I prefer the name _controls.

For me the name "link" is a quite simple concept - a pointer to somewhere. I think of a form as something that you fill out and ship somewhere. The reason I thought of the word "control", is that it is used in Richardson Maturity Model, to describe the "hypermedia level" of REST.

Bear in mind that I am not a native english speaker, so my understanding of the terms may be flawed.

[cainus]

I'm not married to "_links", but I think "control" usually refers to a GUI element... Check out the disambiguation page here: http://en.wikipedia.org/wiki/Control , whereas links are not always GUI elements (like in xlink: http://www.w3.org/TR/xlink/ ).

One of the reasons I went with "_links" is because the common web developer is already really comfy with the term, and I can say "It's just json with links". I think we don't see a lot of real world hypermedia apis because examples are often a bit too academic. I wouldn't want to call it "_affordances" for example, because I'm sure people would find that unapproachable (even though it's probably otherwise the perfect name).

But I agree that usually links are read-only, so I definitely understand your concern. I've been using "_links" in hyper+json in various pieces of software for a couple of years now, so if I change it, I'd like to have a really good reason and a vastly improved solution.

Let me think about that though. Let me know if you get better ideas too. I'd much rather have a mediatype that other people want to use than have the perfect mediatype for just me, so I really appreciate the input.

[oyvindfanebust]

Thanks for your explanation. I do understand your reasons for going with _links, and do not think its a big deal. I did also think of another option: "_hyper". Hints to hypermedia (constraint, affordance, control), and matches hyper+json. What do you think?

[emmanuel]

Pardon me for jumping in uninvited, but for what it's worth, I think _links is preferable to _controls or _forms or just about anything else.

First, they are, as you pointed out @oyvindfanebust, simply pointers to other things. That is exactly the point of HATEOAS (as far as I can tell): allow the server to indicate available related resources and state changes to clients by way of providing links relevant to the current resource.

Second, there is quite of a bit of prior art that has embraced the term links or _links:

1. HAL (Hypermedia Application Language) uses _links in exactly the same way as Hyper+JSON (it permits embedding a _links member as a sibling of the resource attributes)
2. Collection+JSON uses links in a similar way, but with a somewhat different structure than Hyper+JSON.
3. HTTP Link header: This allows encoding links in headers instead of in the document (HTTP body)
4. Link hints (IETF draft): this proposes use of _links in a very similar way to Hyper+JSON, including explicitly declaring what HTTP verbs/methods are allowed for different links (ie., it specifies PUT/POST/PATCH in the same bucket as it specifies GET).

A counterexample is kevinswiber/siren, which uses actions as the key for the collection of related resources and available state changes, but I think the above list firmly establishes links or _links as the correct name for the hypermedia content of a hypermedia content type.

Anyways, just thought I'd chime in. Hope that's helpful.

[oyvindfanebust]

Ok. I'm convinced ;)