

Internet-Draft: JSON Hypertext Application Language (lean format for linking) - AffableSpatula
https://raw.github.com/mikekelly/hal-rfc/master/draft-kelly-json-hal-00.txt

======
jdp
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>

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.

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

~~~
AffableSpatula
Already exists: <https://github.com/s3u/headers.js>

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.

~~~
pfraze
Oh, awesome, thanks.

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.

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

------
robinhowlett
The HAL specification was created by Mike Kelly and a very readable
introduction to it is here: <http://stateless.co/hal_specification.html>

We've been using it recently and we like it a lot.

------
pfraze
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
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
Yeah, it's not a big deal, so I wouldn't worry about it. Taste is really all
it is.

------
pwpwp
I'm biased but I like my own design better:

[https://groups.google.com/forum/?fromgroups#!topic/restful-j...](https://groups.google.com/forum/?fromgroups#!topic/restful-
json/jDNhjfh9hfg) (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
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

------
smoyer
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
:)

already working on a browser: <https://github.com/mikekelly/hal-browser>

very rough demo here: <http://hal-shop.heroku.com/hal_browser.html>

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

------
jchrisa
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
point well made, thanks. I will probably incorporate this in the next version
of the draft.

~~~
jchrisa
Maybe json._self is better than _id since _id is already used by apps where
it's not always an href

------
nulluk
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
fwiw, I used xml2rfc for this, it inserts all the boilerplate for you

<http://xml.resource.org/>

