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.com
*Skype*: axefrog
*Twitter*: @NathanRidley
*Website*: http://axefrog.com / http://nathanridley.com
*Phone: *+61 (0) 475 072789