RE: "Plain JSON" vs Hydra

On 5 Aug 2014 at 22:26, John Walker wrote:
> On 5 Aug 2014, at 22:41, "Markus Lanthaler" wrote:
>> On 5 Aug 2014 at 17:56, Dimitri van Hees wrote:
>>> 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?

The advantage is that a client doesn't have to dereference the URL just to display a label in a UI.


> In other words what are best practices for (de)normalizing info in
> API responses?

It depends :-) I would say that if there are millions of possible things, in other words the likelihood that the client has already seen this specific URL is very low, it makes sense to include such information in a response. If you have flexible enough clients, you can tweak this at runtime.


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

In some cases it might actually would make sense to do so. In most cases, however, you will use the same properties and types over and over again so the client pays the cost of dereferencing them just once. I'm also more and more a fan of including labels for properties etc. in the referenced Hydra ApiDocumentation so that even if you are using hundreds of properties from different vocabularies (or vocabularies using paths such as Schema.org) you only have to make one HTTP request instead of hundreds. I did that for example in the Schema.org event API I just posted a couple of minutes ago.


HTH,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 5 August 2014 21:11:44 UTC