RE: Hypermedia and media types

On 18 Aug 2015 at 20:12, Tomasz Pluskiewicz wrote:
> On 2015-08-18 17:31, Dimitri van Hees wrote:
>> 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.

JSON-LD requires vocabularies that define the semantics of the data. Hydra
is a vocabulary like any other. It doesn't change the processing model of
JSON-LD and thus it doesn't need a different media type. 


> 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).

Yeah, you could look at it that way.


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

... and processing model.

 
>> 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).

How would a client be able to "to paginate through collections of data" in
that 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.

I don't follow. What has that to do with triplestores?


>> As Hydra doesn't
>> have it's own media type, what would be the best practice to achieve
>> this?

You could define a profile as Ruben already mentioned. An alternative might
be to use the Prefer header [1] (either by using "return=minimal" or
defining a new preference).


>> 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 (?)

Referencing the context via the HTTP Link header isn't supported for
application/ld+json. All the information has to be in the payload in that
case.

> application/hal+json (etc.)
>    any other non-LD hypermedia format
> application/rdf+xml and others
>    other RDF formats with hydra


HTH,
Markus


[1] http://tools.ietf.org/html/rfc7240


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 18 August 2015 18:36:29 UTC