Re: How do I bundle in tangential metadata?

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
      From: Nathan Ridley <axefrog@gmail.com>
 To: public-linked-json@w3.org 
 Sent: Tuesday, March 17, 2015 1:23 AM
 Subject: How do I bundle in tangential metadata?
   
Given that the idea of Hypermedia is to also include next steps that a user can take, ala "links", but also the fact that a resource probably only knows about linked data that directly relates to itself, what's the best way to represent a resource *and* linked metadata surrounding the request? For instance, perhaps the resource represents a user on my system, but I also need the user/client to know about general links to other areas of the website, e.g. the "about us" page, the login page, a Hydra entry point, and so forth. If I just return the JSON-LD document representing the requested user, and don't assume that the client has any pre-existing state (as per HATEOAS/REST constraints), then how should that metadata be bundled up in the response? Should I simply be returning a graph instead?
Nathan

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