

HAL is a lean hypermedia type for your RESTful APIs - AffableSpatula
http://stateless.co/hal_specification.html

======
premchai21
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.

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

~~~
premchai21
MIME multipart is pretty good in and of itself, and in particular can
represent a larger space of content types well. I'm trying to imagine how this
interacts with things like URI fragment identifiers, though. MIME has Content-
ID, but that's defined to be a msg-id, which doesn't help much. xml:id might
be more effective in a sense, but then you run into the internal collision
problem again.

Implementationally, hooking up an extra MIME layer is a lot more cumbersome
than it should be. This is theoretically a transient characteristic, but I
have the creeping feeling that that will destroy any attempts to use MIME for
this purpose regardless.

~~~
deno
Well, yes, if the content is inter-connected this is more tricky.

Xml:id assumes unique identifiers within scope, and with multiple documents
that would require a global scope, something that is not standardized and
problematic (it'd require either using UUIDs as IDs or keeping track of
uniqueness in some other way).

I think a better solution would be to use XLink. Assuming each document has
its own canonical link, this is then straightforward:

1\. Make sure each XML document within MIME/Multipart container includes <link
rel="canonical" href="uri:…"/>

2\. Each document in a MIME/Multipart container should refer to other
documents using xlink, i.e. unique URL with a part identifying specific
fragment using XPath (which can then use xml:id in a local scope).

Now, depending on the client following scenarios are possible:

1\. Naïve: Client will perform redundant requests, but will cache documents in
containers, resulting in several HTTP(304) responses.

2\. Smart: Client will notice that referred documents are contained in a
multipart MIME message and will use local versions.

As a bonus, this approach is not dependant on MIME in any way — it will work
just as well with, for example, a ZIP archive.

------
deno
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-
relation...](http://www.iana.org/assignments/link-relations/link-
relations.xml)

[2] <http://www.opensearch.org/Home>

[3] RFC 4287, RFC 5023, RFC 4685, RFC 4946, RFC 5005

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

------
wccrawford
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
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>

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

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

~~~
AffableSpatula
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 :)

