RE: "Plain JSON" vs Hydra

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.


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


>>> 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 19:42:11 UTC