RE: Hypermedia and media types

>> Tomasz Pluskiewicz:
>>
>>> 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.
>>
>> Thing is that I want to be able to specify whether I want hypermedia
> (Hydra in the JSON-
>> LD case) in my response or not.
>
> Why? To reduce the response size or is there another reason?

- If I already have a non-hypermedia response in place and want to add hypermedia afterwards (JSON API and HAL break the structure for example)
- If I only want to retrieve the data (which I then can copy 1:1 to a NoSQL DB for example)
- And perhaps there are use cases where people are bound to response sizes, I don't know my consumer(!)

>> HAL, JSON-API and all the other non-LD Hypermedia
>> standards out there allow me to do so using the Accept header because they
> have their own
>> media types.
>>
>> Markus Lanthaler:
>>
>>> How would a client be able to "to paginate through collections of data"
> in
>>> that case?
>>
>> In that case they probably don't want to paginate. I don't know my
> consumers. But I do
>> know that as a consumer myself, I want the option to fetch a resource
> without hypermedia.
>> For instance when I want to have the RDF version of the resource, using
> content-
>> negotiation. I don't need hypermedia in there. And that's exactly my
> point: an API is just
>> another way to present data. If you present information (LD), then I think
> hypermedia
>> controls have nothing to do with the resource itself.
>
> I know that you very well know that LD stands for *Linked* Data so I'm a bit
> confused that you say you want it without hypermedia controls. Simple links
> are also "hypermedia controls". So, are you referring to Hydra operations
> here? Just that or something else as well?

An 'author'  is a property of a 'book', whether it's a physical paperback, an RDF resource or an application/json body. Providing links to identify which 'author' exactly we mean and perhaps resolve to pages with more information about this particular 'author' is the great thing of Linked Data (and JSON-LD) in my opinion. Links to navigate within the particular API can perhaps be described using the Hydra vocabulary but has nothing to do with the 'book' itself. You know I'm a huge fan of getting JSON data in triplestores via JSON-LD and the great feature to convert JSON-LD to RDF using a single method. If I start with a raw CSV of my book collection and end up with a triplestore with with API information (which is useless in that 'context' ;-)) I am not satisfied. Of course, you could provide a different 'context' to reach that goal, but my unknown consumers are lazy (and mistrustful of everything that has to do with 'Linked Data'). By the way, if you store it 1:1 in a triplestore, unfortunately the response size does matter...

>> An allowed HTTP method has nothing to do with a 'book' for example.
>>
>> Thomas Hoppe:
>>
>>> That's of course true and that's why you would not store them in your
>>> persistence layer.
>>> We enrich the resources read from the database (there is no nee to
>>> employ a triple store btw.)
>>> with the operations dynamically when they are delivered to solve this.
>>
>> This is exactly what I mean! So if the consumer wants to fetch the 'real'
> data (which comes
>> directly out of the persistence layer, ofcourse with some authorisation in
> mind, but you
>> know what I mean) he/she should be able to request that.
>>
>>
>> Thomas Hoppe:
>>
>>> Building APIs with hydra and JSON-LD for 3 years now and knowing those
>>> others
>>> that are around [1] I can tell you that this is noble goal but if you
>>> are in a typical
>>> project setting hardly possible because you will get killed by the
> effort.
>>> If you are talking about dumb transformation of serialization formats
>>> like JSON-LD to RDF/XML etc. then you are certainly right.
>>> But even supporting JSON-LD (+Hydra) and plain JSON is a whole different
> story.
>>> There is so much more you need to consider and implement in your API
>>> server for JSON-LD compared to JSON.
>>> Not to mention the challanges if you have to drive a "procedural model"
>>> (operations in the case of hydra). There is simply not
>>> a 1:1 relation of concepts in hydra, HAL, siren, JSON API etc.
>>
>> The reason I started this discussion is because we are working on a tool
> which automates
>> this, making it easier for people to support multiple hypermedia types.
>
> Interesting. I wonder how you intend to reconcile the completely different
> processing and data models.

That's what makes it interesting indeed, but it wasn't meant to be ready in one hour ;-)

>> However, I still think
>> people should be able to 'disable' hypermedia in the response. Almost
> everyone returns
>> application/hal+json when a consumer requests application/json.
>
> Who is almost everyone? What breaks by doing so? It certainly is valid
> application/json. Maybe people don't care about the extra data that's
> there... I wouldn't. I would have to map it to my internal representation
> anyway and there's no way to automate that as message semantics depend
> solely on its JSON structure (in both cases).
>
>
>> This breaks backwards
>> compatibility if I ever want to return the plain JSON without hypermedia,
>
> Why? It's still valid JSON. Every structural change is a breaking change in
> JSON, HAL, Siren and most other approaches. JSON-LD is immune to that. It
> couples at the level of the vocabulary.

I might be wrong, but in the example of the book's 'author' it isn't possible to add a link to the actual author without editing the structure in JSON-LD right? The vocabulary tells me that the "author"  in "author: Markus" is actually a "http://schema.org/author". If I want "Markus" to be the object:

{
  @id: "http://www.markus-lanthaler.com",
  @type: "http://schema.org/Person",
  "label": "Markus"
}

I'll need to edit the structure. So, if I start an API returning the above response on an application/json request, I can't return a plain application/json response in the future without breaking backwards compatibility anymore.

>> so I think this
>> assumption is wrong. If you support both application/json and
> application/hal+json, the
>> consumer (which I don't know!) can choose to accept hypermedia or not. If
> you support
>> application/ld+json the consumer appearantly can not make this choice,
> because the server
>> decides if the application/ld+json response contains Hydra or not.
>
> That server decides anyway what it returns. The client needs to deal with
> what it gets. It can ignore stuff it doesn't care about (see Mike's
> must-ignore comment).

I firmly disagree on this, but perhaps that's because Dutch developers are even more stubborn that regular developers :-)
It doesn't work that way if you don't know your "Large Set of Unknown Developers" and want people to use your API instead of the API of your competitors.

>> Markus Lanthaler:
>>
>>> 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).
>>
>> Interesting, I'm going to investigate the "return=hypermedia" option ;-)
>
> :-)
>
> Let us know if you gather some stats of how popular that option turns out to
> be. My guess is that most developers don't care about a little extra data in
> the response.

I definitely will! I don't think they care about little extra data, however I do think they care about little extra complexity. The fact is: I don't know. So if we could provide all different responses, it's all up to them. The only thing I'm struggling with right now is that I can't find a proper way to provide both JSON-LD without Hydra *and* JSON-LD with Hydra. Apart from why we would want that, do you think the Prefer header is the right technical solution for this?

> --
> Markus Lanthaler
> @markuslanthaler
>
>

Received on Thursday, 20 August 2015 07:32:06 UTC