Re: "Plain JSON" vs Hydra

Hi Markus,

On 5 Aug 2014, at 22:41, "Markus Lanthaler" <markus.lanthaler@gmx.net> wrote:

> Hi Dimitri,
> 
> On 5 Aug 2014 at 17:56, Dimitri van Hees wrote:
>> The most important reason for me is backwards compatibility. If I
>> have had enough resources I could make a JSON-LD API right away, but
>> for the sake of 'sellability' of API's (which happen to be very
>> difficult at all in our business at least), I like the idea of
>> 'upgrading' responses with JSON-LD in a later stadium, when people
>> already use the data provided in the API and the investment has
>> proven itself already.
> 
> In most cases you can get the best of both quite easily by planning a little
> bit ahead. But I completely understand this pragmatic approach and agree
> that in a lot of cases it is a the right thing to do. That being said, there
> are a couple of tricks that minimize those "breaking changes" (see below).
> 
> 
>> Now I know that it's completely valid to just add a link to a
>> context file in the response header not breaking backwards
>> compatibility, but then you don't get the full benefits of JSON-LD
>> in my opinion (like which actual @type a value is). Furthermore,
> 
> The question is whether such information wouldn't also be very useful in a
> pragmatic JSON-only API!?
> 
> 
>> when there is a triplestore in place already, converting triples
>> back to JSON-LD doesn't really give me a developer friendly
>> response.
> 
> You would need to use something like framing to achieve that or use some (I
> think rather simple) heuristics.
> 
> 
>> For example, if I have
>> 
>> {
>>   "city": "London"
>> }
>> 
>> Just converting it to
>> 
>> {
>>   "@context": {
>>     "city": "http://schema.org/homeTown"
>>   },
>>   "city": "London"
>> }
>> 
>> Doesn't give me the full benefits because I still can't fetch more
> information
>> about London.
> 
> It is easily possible though:
> 
>  {
>    "@context": {
>      "city": { "@id": "http://schema.org/homeTown", "@type": "@vocab" },
>      "London": "http://dbpedia.org/resource/London"
>    },
>    "city": "London"
>  }
> 
> See a live example at http://bit.ly/1sbfEFp
> 
> 
>> I'd like to see this instead:
>> 
>> {
>>   "@context": {
>>     "city": {"@id": "http://schema.org/homeTown", "@type": "@id"}
>>   },
>>   "city": {
>>     "label": "London",
>>     "@id": "http://dbpedia.org/resource/London",
>>     "@type": "http://schema.org/City"
>>   }
>> }
> 
> You are adding a whole lot of information that wasn't there before. So
> obviously you need to change the document.

Assuming the info that is added is also available by dereferencing the URI for London, is there any real advantage to restate it in each response about a person who lives in London? In other words what are best practices for (de)normalizing info in API responses?

I mean why not include the labels and types of the properties that are used in the response too? (just to give an extreme)

>> Which is a completely different response. Besides the design process
>> takes more time (which links and vocabularies are we going to use)
>> while we'd like to use rapid development to get the API 'out there'
>> to convince people to use it.
> 
> That's true. Deciding which things will probably be resources (JSON objects)
> and which won't isn't very time consuming though and helps to avoid most of
> these "problems".
> 

Some guidance on these matters:
http://patterns.dataincubator.org/book/link-not-label.html

> 
>>>> When implementing Hydra, there is no alternative to 'explore'
>>>> your API in the "normal" application/json response.
> 
> Referencing a context and a Hydra ApiDocumentation (haven't done that in the
> example above) from HTTP Link headers gives you already quite a bit I'd say.
> 
> 
>>> Why would that be necessary then? People who want generic
>>> hypermedia controls, sign up for responses that allow for generic
>>> hypermedia controls.
>>> 
>>>> I could implement something like HAL for that response I guess, but
>>>> then I'd have to do both.
> 
> And you would have to change your JSON responses as well, this time adding
> "_links".
> 
> 
>>> You could still choose to strip off the information in the plain
>>> JSON version; the interpretation will then simply be proprietary.
>>> 
>>> I.e., still use Hydra properties (structurally speaking), just not
>>> actually. Or see it as an “implicit external context”.
>> 
>> Yes, I like this idea!
> 
> I'm not sure that this really simplifies things but if it addresses your
> concerns, fine :-)
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
>

Received on Tuesday, 5 August 2014 20:26:45 UTC