4 ms·

HAL is a lean hypermedia type for your RESTful APIs

12 points by AffableSpatula 15y ago

wccrawford 15y ago
Ah man. Where was this when I was making my latest REST service!? Ah well. I'll have to remember it for the next one.
- AffableSpatula 15y ago
  yeah.. sorry about that ;) Sketched it out about a year ago, the design has changed a tiny bit since then but it's basically the same http://bit.ly/acgCyY http://bit.ly/acgCyY
deno 15y ago
No mention of IANA's link relations[1], OpenSearch[2] and Atom[3] which seems to cover almost anything and beyond what ‘HAL’ specifies. For JSON, JSONSchema specifies standard way of including hyperlinks in a document, but of course no one, that uses JSON in the first place, even cares. [1] http://www.iana.org/assignments/link-relations/link-relations.xml http://www.iana.org/assignments/link-relations/link-relation... [2] http://www.opensearch.org/Home http://www.opensearch.org/Home [3] RFC 4287, RFC 5023, RFC 4685, RFC 4946, RFC 5005
- arethuza 15y ago
  Having pretty much sworn off XML, at least for my own projects, I've been pondering what JSON should look like that if you are going all the way to HATEOAS and you have links in your data returned from your REST interface.
  - deno 15y ago
    You will reinvent XML with uglier syntax, all while hurting yourself and Open Web. I've managed to somehow get into that argument before, so maybe there's something worth reading there: [1], [2]. [1] http://news.ycombinator.com/item?id=2623824 http://news.ycombinator.com/item?id=2623824 [2] http://news.ycombinator.com/item?id=2588606 http://news.ycombinator.com/item?id=2588606
    - arethuza 15y ago
      Don't get me wrong - I'm not an XML hater by any means it's just that JSON appeals to be as a syntax - possibly as I did Lisp development for a number of years and the relative similarity of JSON to s-expressions appeals to me.
      - deno 15y ago
        Well, I only care for public Web APIs. Though if you're not writing your documents by hand, I don't see how the syntax matters (it's just library then, anyway). And if you are writing your documents by hand, there are better solutions than JSON — for example YAML (which is excellent!).
- AffableSpatula 15y ago
  Yep, it definitely should be making reference to the IANA registry (will likely do this by referencing Web Linking RFC5988). The point here was not to necessarily invent new capabilities, but to take a unique position in its design and bring together the most consistently useful assets of existing types whilst filtering out the noise. It's much healthier for the web than just returning plain JSON/XML or a custom media type.
  - deno 15y ago
    It's preferable to return correctly annotated (with elements from aforementioned namespaces) XML, rather than ‘plain XML.’ My point was, that this vocabulary already exists and there's no reason to invent new (incompatible) one. If you think you can provide some improvement to any of that, you should definitely contribute to that standards. It's great that you care about what you output at all. Most developers don't, some even try to embrace their ignorance. I think that there's certainly a lack of user-friendly resources, that introduce developers to the best practices regarding data formats and public APIs. For example, a website, that would catalogue and provide examples of usage of certain conventions, would be, undeniably, a godsend. I hope we can all make the Web a better place, and just adopting already defined standards would be a tremendous achievement!
    - AffableSpatula 15y ago
      HAL already incorporates standards for the URI template spec and the CURIE syntax. It's also going to be rejigged to incorporate terminology direct from the Web Linking RFC. The above being the case, it doesn't seem as if HAL is re-inventing anything significant from a standards perspective, and avoids inheriting baggage associated with pulling in elements from other namespace. Perhaps not a completely 'pure' approach, but the primary objective is simplicty - and I think doing things this way is a good balance. If this is something you feel strongly about, please join the google group and raise it there so we can discuss merits and trade-offs in more depth.
premchai21 15y ago
Reading this leaves me troubled. Why not the XLink vocabulary, for instance? I can understand something like this appearing for JSON if only so that people have an intrametalinguistic transition path for their JSON APIs, but letting so much existing work on interoperable XML representations fall by the wayside could be unfortunate. Did you actually register the media types? “Any and all elements are legal in a HAL representation provided they do not conflict with HAL's reserved elements.” If I'm reading this right: please, please, no. Not in XML. Allocate a namespace URI and use it. Let's not start down the path of everyone having to watch out for everyone else's element names again. The idea of identifying multiple packed related resources (which could otherwise be top-level resources) in the same document is interesting. I don't immediately recall specific prior specifications there, but I'd definitely want to go through the W3C site with a fine-toothed comb to check. E.g., Atom feeds already can embed XML fragments of almost any other type (though most commonly XHTML) as entry content; there may be some evolution of that available.
- AffableSpatula 15y ago
  Might be worth exploring if re-using stuff like XLink makes sense and is within keeping of the objective to keep things simple. Probably better to discuss that on the google group than here, feel free to join and raise it there. At the moment, it's registered with IANA as application/vnd.hal+xml, although I don't think it makes a huge difference either way at this point time. Element collision is not a big deal as clients should be determining element semantics on a per-resource basis and - importantly - in the context of the link relation leading to it (from either a resource or a link). You will find similarity with other media types like atom and rdf. Basically, it's designed to be more generic than atom and less convoluted than RDF.
- deno 15y ago
  YAML specifies standard way of including multiple documents in a single stream/file. With XML (assuming XSD-compatible parser), you can always extend the NS and have several documents in a single container (thus single stream/file), but I don't see how that would be preferable to just using MIME/Multipart.
zacharyvoase 15y ago
Not a single mention of RDF throughout. Am I missing something, or is this wheel reinvention?
- AffableSpatula 15y ago
  The intention with hal was to keep things as simple as possible. RDF (and its related media types) don't do a very good job of this, in my opinion. I think the real-world usage is a good indicator of whether RDF is appropriate for most people's use cases. There's probably some node.js analogy to be made here, too :)
irickt 15y ago
Here's a nicely done comparable: http://json-ld.org/ http://json-ld.org/ Compatible with RDF while keeping it simple.

Ah man. Where was this when I was making my latest REST service!? Ah well. I'll have to remember it for the next one.

AffableSpatula 15y ago
yeah.. sorry about that ;) Sketched it out about a year ago, the design has changed a tiny bit since then but it's basically the same http://bit.ly/acgCyY http://bit.ly/acgCyY

deno 15y ago

No mention of IANA's link relations[1], OpenSearch[2] and Atom[3] which seems to cover almost anything and beyond what ‘HAL’ specifies. For JSON, JSONSchema specifies standard way of including hyperlinks in a document, but of course no one, that uses JSON in the first place, even cares. [1] http://www.iana.org/assignments/link-relations/link-relations.xml http://www.iana.org/assignments/link-relations/link-relation... [2] http://www.opensearch.org/Home http://www.opensearch.org/Home [3] RFC 4287, RFC 5023, RFC 4685, RFC 4946, RFC 5005

arethuza 15y ago
Having pretty much sworn off XML, at least for my own projects, I've been pondering what JSON should look like that if you are going all the way to HATEOAS and you have links in your data returned from your REST interface.
- deno 15y ago
  You will reinvent XML with uglier syntax, all while hurting yourself and Open Web. I've managed to somehow get into that argument before, so maybe there's something worth reading there: [1], [2]. [1] http://news.ycombinator.com/item?id=2623824 http://news.ycombinator.com/item?id=2623824 [2] http://news.ycombinator.com/item?id=2588606 http://news.ycombinator.com/item?id=2588606
  - arethuza 15y ago
    Don't get me wrong - I'm not an XML hater by any means it's just that JSON appeals to be as a syntax - possibly as I did Lisp development for a number of years and the relative similarity of JSON to s-expressions appeals to me.
    - deno 15y ago
      Well, I only care for public Web APIs. Though if you're not writing your documents by hand, I don't see how the syntax matters (it's just library then, anyway). And if you are writing your documents by hand, there are better solutions than JSON — for example YAML (which is excellent!).
AffableSpatula 15y ago
Yep, it definitely should be making reference to the IANA registry (will likely do this by referencing Web Linking RFC5988). The point here was not to necessarily invent new capabilities, but to take a unique position in its design and bring together the most consistently useful assets of existing types whilst filtering out the noise. It's much healthier for the web than just returning plain JSON/XML or a custom media type.
- deno 15y ago
  It's preferable to return correctly annotated (with elements from aforementioned namespaces) XML, rather than ‘plain XML.’ My point was, that this vocabulary already exists and there's no reason to invent new (incompatible) one. If you think you can provide some improvement to any of that, you should definitely contribute to that standards. It's great that you care about what you output at all. Most developers don't, some even try to embrace their ignorance. I think that there's certainly a lack of user-friendly resources, that introduce developers to the best practices regarding data formats and public APIs. For example, a website, that would catalogue and provide examples of usage of certain conventions, would be, undeniably, a godsend. I hope we can all make the Web a better place, and just adopting already defined standards would be a tremendous achievement!
  - AffableSpatula 15y ago
    HAL already incorporates standards for the URI template spec and the CURIE syntax. It's also going to be rejigged to incorporate terminology direct from the Web Linking RFC. The above being the case, it doesn't seem as if HAL is re-inventing anything significant from a standards perspective, and avoids inheriting baggage associated with pulling in elements from other namespace. Perhaps not a completely 'pure' approach, but the primary objective is simplicty - and I think doing things this way is a good balance. If this is something you feel strongly about, please join the google group and raise it there so we can discuss merits and trade-offs in more depth.

premchai21 15y ago

Reading this leaves me troubled. Why not the XLink vocabulary, for instance? I can understand something like this appearing for JSON if only so that people have an intrametalinguistic transition path for their JSON APIs, but letting so much existing work on interoperable XML representations fall by the wayside could be unfortunate. Did you actually register the media types? “Any and all elements are legal in a HAL representation provided they do not conflict with HAL's reserved elements.” If I'm reading this right: please, please, no. Not in XML. Allocate a namespace URI and use it. Let's not start down the path of everyone having to watch out for everyone else's element names again. The idea of identifying multiple packed related resources (which could otherwise be top-level resources) in the same document is interesting. I don't immediately recall specific prior specifications there, but I'd definitely want to go through the W3C site with a fine-toothed comb to check. E.g., Atom feeds already can embed XML fragments of almost any other type (though most commonly XHTML) as entry content; there may be some evolution of that available.

AffableSpatula 15y ago
Might be worth exploring if re-using stuff like XLink makes sense and is within keeping of the objective to keep things simple. Probably better to discuss that on the google group than here, feel free to join and raise it there. At the moment, it's registered with IANA as application/vnd.hal+xml, although I don't think it makes a huge difference either way at this point time. Element collision is not a big deal as clients should be determining element semantics on a per-resource basis and - importantly - in the context of the link relation leading to it (from either a resource or a link). You will find similarity with other media types like atom and rdf. Basically, it's designed to be more generic than atom and less convoluted than RDF.
deno 15y ago
YAML specifies standard way of including multiple documents in a single stream/file. With XML (assuming XSD-compatible parser), you can always extend the NS and have several documents in a single container (thus single stream/file), but I don't see how that would be preferable to just using MIME/Multipart.

zacharyvoase 15y ago

Not a single mention of RDF throughout. Am I missing something, or is this wheel reinvention?

AffableSpatula 15y ago
The intention with hal was to keep things as simple as possible. RDF (and its related media types) don't do a very good job of this, in my opinion. I think the real-world usage is a good indicator of whether RDF is appropriate for most people's use cases. There's probably some node.js analogy to be made here, too :)

irickt 15y ago

Here's a nicely done comparable: http://json-ld.org/ http://json-ld.org/ Compatible with RDF while keeping it simple.