Re: How do I bundle in tangential metadata?

Hi Nathan,
FYI HAL is read/write too (if by that you mean it supports the full set of HTTP verbs) - you just issue an OPTIONS request at the link href rather than processing a hydra:Operation declaration.
cheers
Julian

      From: Nathan Ridley <axefrog@gmail.com>
 To: "public-linked-json@w3.org" <public-linked-json@w3.org> 
 Sent: Saturday, March 21, 2015 9:57 PM
 Subject: Re: How do I bundle in tangential metadata?
   
Just thought I'd propose an answer to my own question after studying the two in more depth; HAL is read-only, whereas Hydra is read/write. So if a developer only has simple needs, HAL is much easier to understand and implement. If you want to properly describe an API though, Hydra offers a much richer set of capabilities which make that possible. HAL is not able to cover that use case.


On 21 March 2015 at 18:12, Nathan Ridley <axefrog@gmail.com> wrote:

Hi Julian, sorry for the slow reply; I've been off work for a few days. Thanks for your insights; they've given me plenty to think about. Do you have any opinion on Hydra as it compares to HAL? Clearly Hydra is more ambitious than HAL in terms of what it offers, though I don't yet have a sense of how the two compare in practice, other than the fact that HAL appears to offer a simplified subset of what Hydra offers.
Nathan

Hi Nathan,

I think this is an interesting question, and one which it took me a while to unpick when I started building linked data APIs. The thing to remember is that if you are exposing linked data via a REST interface then, as you note, URLs are typically being used for two fundamentally different concerns - one relating to state and another relating to behaviour:

1. Thinking about a resource in REST terms, i.e. as a finite state machine, hypermedia is used to drive the state transitions - i.e. it is a behavioural concern.
2. Thinking about a resource in linked data terms, URLs are used to fully qualify encoded data - i.e. they are a state concern.

I see these as entirely complimentary: you just need to be clear about when you are using URLs as a state transfer mechanism vs when you are using URLs for data encoding.

If you think about the program sequence of a client requesting a resource from a linked data API, the way in which the API adds value to the program flow is typically by reducing client-server coupling and by making the graph into something as consumer-friendly as possible. In my experience that has meant merging state transfer/API navigability identifiers into the response, and also simplifying the graph e.g. by flattening/dereifying provenance information, etc. Typically my API clients are web-based and they want something as standard JSON-like as possible. For such representations, my standard pattern is now to use:

1. HAL (http://stateless.co/hal_specification.html) for the behavioral concerns
2. JSON-LD for the resource state encoding
3. JSON-LD framing to make the response look as close to standard JSON as possible
4. a declared MIME type of 'application/hal+json'
5. a Link header which references the associated external json-ld contexts.

That gives all the benefits of linked data for those clients who care about it, but on more of an 'opt-in' basis where other consumers who only care about late-binding to your API to protect against future versioning issues can basically treat it as a standard RESTful JSON interface.

cheers

Julian






-- 
Google: axefrog@gmail.comSkype: axefrogTwitter: @NathanRidleyWebsite: http://axefrog.com / http://nathanridley.comPhone: +61 (0) 475 072789