Like the idea. One suggestion - the value at json._links.self will often be a unique identifier. Maybe some provision can be made for this to live at a top level, like json._id
There are strong arguments against that idea I'm sure, but consider the boon to adoption you can get by having the only required thing be a top-level element not a nested attribute
Yeah, that really bothers me about web frameworks. It's particularly problematic for type negotiation, which is ignored pretty often in my experience (people tend to indicate type in the uri, using ".json," for instance).
In my opinion, Link Headers are not a good option as the primary hypermedia of your API. They are useful for adding links to responses with a Content-Type that is not capable of expressing a link, and they are useful for protocols (http://tools.ietf.org/html/draft-nottingham-linked-cache-inv...), but they are not reliable enough for 'every day use'. HTTP Headers are frequently stripped, modified, and generally abused by intermediaries, and there is also the issue of practical upper limits on the size of the HTTP Header block.
I agree with this personally, because this spec is adding meta-data to the body, and headers are pretty much made for that.
The practical problem is that you have to parse the link header, and it's not simple enough for common use. I think, if we want to use headers, we need to build some JS utilities for the different specs that abstract away any parsing.
There are problems with using Link headers, I think you will find less friction in practice by treating links as 'proper data' and putting them in the content body using a media type like this.
You may be right-- HTML employs meta-data in the header, and there are good reasons for it. I like to think that I can put my meta links in the headers and content links in the json, but I may be overworking for a minor gain in simplicity.
Sorry to be off topic here but is there a standard for laying out specification documents like this that i can read up on? When ever I come across these they are always well thought out and nicely presented.
It would be a nice way to present ideas due to the documents feeling well thought out and structured as apposed to a simple idea scribbled down.
One suggestion that's probably way too late in the game: underscores are often used to indicate privacy, membership, or a special state compared to the non-underscore-prefixed key. I think a dollar-sign prefix might be a better indication of meta-data.
I love the idea of this being standardized and am immediately thinking that a generic browser of application/hal+json resources would be a great developer tool.
I tend to agree with the idea that self should be top-level, but the other thing I'd like to have in the specification is versioning for both the specification itself and the API. How about something like:
{
...
"_version": {
"hal": <some HAL version string>,
"api": <some API version string>
},
...
}
Thanks for the thought you've obviously put into this ... we'll all benefit eventually!
Looks a lot like what I "saw in my head". Some code to get around SOP would let you point it at anyone's API ... a great way to learn an API is to see it with real data and you'd be able to navigate around the resources at will.
This seems to be covered by json schema already does it not?
http://tools.ietf.org/html/draft-zyp-json-schema-03
see section 6 - Hyperschema, which lays out a way of describing which parts of a JSON object contains href links. This seems more elegant to me.
24 comments
[ 2.8 ms ] story [ 44.4 ms ] threadThere are strong arguments against that idea I'm sure, but consider the boon to adoption you can get by having the only required thing be a top-level element not a nested attribute
https://groups.google.com/forum/?fromgroups#!topic/restful-j... (Google Groups breakage; link is meant to go to first post in discussion)
Instead of requiring that objects have a special _links property, you can put links anywhere in a JSON structure, just like in a HTML document.
Everything of the form
anywhere in a JSON object is treated as a link.- Resources - Resource state - Links
hal+json results in more uniform representations, which makes it easier to write generic client + server client libraries for
From their examples, this is the equivalent representation:
It also allows for multiple Link headers to be sent instead of the comma-separated version.Github already use hal+json's _links convention in their latest Pull request API: http://developer.github.com/v3/pulls/
The practical problem is that you have to parse the link header, and it's not simple enough for common use. I think, if we want to use headers, we need to build some JS utilities for the different specs that abstract away any parsing.
There are problems with using Link headers, I think you will find less friction in practice by treating links as 'proper data' and putting them in the content body using a media type like this.
You may be right-- HTML employs meta-data in the header, and there are good reasons for it. I like to think that I can put my meta links in the headers and content links in the json, but I may be overworking for a minor gain in simplicity.
http://xml.resource.org/
We've been using it recently and we like it a lot.
Hopefully it holds up even though this choice might not be to everyone's taste?
I tend to agree with the idea that self should be top-level, but the other thing I'd like to have in the specification is versioning for both the specification itself and the API. How about something like:
{ ... "_version": { "hal": <some HAL version string>, "api": <some API version string> }, ... }
Thanks for the thought you've obviously put into this ... we'll all benefit eventually!
already working on a browser: https://github.com/mikekelly/hal-browser
very rough demo here: http://hal-shop.heroku.com/hal_browser.html