4 ms·

Internet-Draft: JSON Hypertext Application Language (lean format for linking)

17 points by AffableSpatula 14y ago

jchrisa 14y ago
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
- AffableSpatula 14y ago
  point well made, thanks. I will probably incorporate this in the next version of the draft.
  - jchrisa 14y ago
    Maybe json._self is better than _id since _id is already used by apps where it's not always an href
pwpwp 14y ago
I'm biased but I like my own design better: https://groups.google.com/forum/?fromgroups#!topic/restful-json/jDNhjfh9hfg 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 { "$href": <url> [,"rel": <token>] [,"type": <media-type>] } anywhere in a JSON object is treated as a link.
- AffableSpatula 14y ago
  Personally I prefer HAL's model because it is couched in web terminology, i.e: - Resources - Resource state - Links hal+json results in more uniform representations, which makes it easier to write generic client + server client libraries for
jdp 14y ago
The _links field may not be necessary. There is already an HTTP Link header proposal, and is already being used by API's like GitHub's: http://www.w3.org/Protocols/9707-link-header.html http://www.w3.org/Protocols/9707-link-header.html From their examples, this is the equivalent representation: Link: <http://www.tld/orders/523>;rel=self, <http://www.tld/warehouse/56>;rel=warehouse, <http://www.tld/invoices/873>;rel=invoice It also allows for multiple Link headers to be sent instead of the comma-separated version.
- pwpwp 14y ago
  But what if you want to store the links in the content? (E.g. if you have no control over the headers a server sends.)
  - danellis 14y ago
    Also, what if you want to persist the content?
- jchrisa 14y ago
  Problem with headers is that they basically don't exist as far as Joe beginner programmer is concerned.
  - pfraze 14y ago
    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).
- AffableSpatula 14y ago
  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-02 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. Github already use hal+json's _links convention in their latest Pull request API: http://developer.github.com/v3/pulls/ http://developer.github.com/v3/pulls/
nulluk 14y ago
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.
- AffableSpatula 14y ago
  fwiw, I used xml2rfc for this, it inserts all the boilerplate for you http://xml.resource.org/ http://xml.resource.org/
robinhowlett 14y ago
The HAL specification was created by Mike Kelly and a very readable introduction to it is here: http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html We've been using it recently and we like it a lot.
pfraze 14y ago
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.
- AffableSpatula 14y ago
  Yes I'm loathe to change this. Some have even suggested removing a prefix altogether since underscores are 'not ruby-like'. Hopefully it holds up even though this choice might not be to everyone's taste?
  - pfraze 14y ago
    Yeah, it's not a big deal, so I wouldn't worry about it. Taste is really all it is.
smoyer 14y ago
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!
- AffableSpatula 14y ago
  :) already working on a browser: https://github.com/mikekelly/hal-browser https://github.com/mikekelly/hal-browser very rough demo here: http://hal-shop.heroku.com/hal_browser.html http://hal-shop.heroku.com/hal_browser.html
  - smoyer 14y ago
    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.
ZenPsycho 14y ago
This seems to be covered by json schema already does it not? http://tools.ietf.org/html/draft-zyp-json-schema-03 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.

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

AffableSpatula 14y ago
point well made, thanks. I will probably incorporate this in the next version of the draft.
- jchrisa 14y ago
  Maybe json._self is better than _id since _id is already used by apps where it's not always an href

pwpwp 14y ago

I'm biased but I like my own design better: https://groups.google.com/forum/?fromgroups#!topic/restful-json/jDNhjfh9hfg 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 { "$href": <url> [,"rel": <token>] [,"type": <media-type>] } anywhere in a JSON object is treated as a link.

AffableSpatula 14y ago
Personally I prefer HAL's model because it is couched in web terminology, i.e: - Resources - Resource state - Links hal+json results in more uniform representations, which makes it easier to write generic client + server client libraries for

jdp 14y ago

The _links field may not be necessary. There is already an HTTP Link header proposal, and is already being used by API's like GitHub's: http://www.w3.org/Protocols/9707-link-header.html http://www.w3.org/Protocols/9707-link-header.html From their examples, this is the equivalent representation: Link: <http://www.tld/orders/523>;rel=self, <http://www.tld/warehouse/56>;rel=warehouse, <http://www.tld/invoices/873>;rel=invoice It also allows for multiple Link headers to be sent instead of the comma-separated version.

pwpwp 14y ago
But what if you want to store the links in the content? (E.g. if you have no control over the headers a server sends.)
- danellis 14y ago
  Also, what if you want to persist the content?
jchrisa 14y ago
Problem with headers is that they basically don't exist as far as Joe beginner programmer is concerned.
- pfraze 14y ago
  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).
AffableSpatula 14y ago
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-02 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. Github already use hal+json's _links convention in their latest Pull request API: http://developer.github.com/v3/pulls/ http://developer.github.com/v3/pulls/

nulluk 14y ago

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.

AffableSpatula 14y ago
fwiw, I used xml2rfc for this, it inserts all the boilerplate for you http://xml.resource.org/ http://xml.resource.org/

robinhowlett 14y ago

The HAL specification was created by Mike Kelly and a very readable introduction to it is here: http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html We've been using it recently and we like it a lot.

pfraze 14y ago

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.

AffableSpatula 14y ago
Yes I'm loathe to change this. Some have even suggested removing a prefix altogether since underscores are 'not ruby-like'. Hopefully it holds up even though this choice might not be to everyone's taste?
- pfraze 14y ago
  Yeah, it's not a big deal, so I wouldn't worry about it. Taste is really all it is.

smoyer 14y ago

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!

AffableSpatula 14y ago
:) already working on a browser: https://github.com/mikekelly/hal-browser https://github.com/mikekelly/hal-browser very rough demo here: http://hal-shop.heroku.com/hal_browser.html http://hal-shop.heroku.com/hal_browser.html
- smoyer 14y ago
  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.

ZenPsycho 14y ago

This seems to be covered by json schema already does it not? http://tools.ietf.org/html/draft-zyp-json-schema-03 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.