Re: Hypermedia and media types

On 2015-08-18 17:31, Dimitri van Hees wrote:
> Hi all,
>
> I'm designing an API and I am struggling with the choice of supported
> hypermedia standards. Fact: we need to paginate through collections
> of data. I'd like to offer both plain JSON and JSON-LD and let the
> client choose which response he wants using the accept header. This
> is no problem because we can simply use application/json and
> application/ld+json.
>
> Problems arise when we also want to add hypermedia to the response.
> In my opinion, one of the hypermedia versions of my the JSON response
> is HAL, returned when application/hal+json is being requested. The
> hypermedia version of the JSON-LD response should be Hydra, but as
> far as I know Hydra doesn't have it's own media type because it's in
> fact just valid application/ld+json. However, JSON-LD is also in fact
> just valid application/json, yet still has it's own media type. Just
> like HAL by the way, which is also just valid application/json.

Yes, but the opposite is not true. Any JSON document isn't valid JSON-LD 
or HAL. On the other hand any JSON-LD document is always a valid Hydra 
document (albeit likely without any hypermedia controls).

Thus you don't need a media type for Hydra, because it is always 
JSON-LD. That is unlike HAL and other non-LD approaches, which force a 
completely different document structure.

>
> I think that one of the nicest things of JSON-LD is that it can be
> converted to RDF and that the URL actually is the object itself. So I
> want to give people the choice between fetching just the resource in
> JSON-LD *and* fetching the resource with hypermedia (Hydra in this
> case). In my opinion, methods, operations and validations has got
> nothing to do with the data itself, so I can imagine use cases where
> I don't want that data in a triplestore for example. As Hydra doesn't
> have it's own media type, what would be the best practice to achieve
> this?
>
> The same counts for the non LD responses by the way. There  are so
> many hypermedia standards out there that I can't choose which one to
> use. In fact I think I'm about to start supporting them all and let
> the client choose which one to use. But then again, there should also
> be a possibility to fetch just the plain old JSON object, without any
> hypermedia. Then again, most people always return hypermedia (say
> application/hal+json), even when the accept header is
> application/json. Perhaps there should be something like
> application/raw+json... ;-)

I would go for plain JSON for application/json but with a twist.

application/json
   JSON-LD with @context in header
   no Hydra
   cleanest JSON form, but still LD
   see http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld

application/ld+json
   JSON-LD with Hydra
   @context inline (?)

application/hal+json (etc.)
   any other non-LD hypermedia format

application/rdf+xml and others
   other RDF formats with hydra

>
> Any thoughts on this?
>
> Regards,
>
> Dimitri van Hees
>

Received on Tuesday, 18 August 2015 18:12:50 UTC