RE: "Plain JSON" vs Hydra

On 6 Aug 2014 at 17:42, Dimitri van Hees wrote:
>> Don't underestimate the power of hypermedia though. A simple JSON
>> based Web API doesn't have that many advantages over a CSV file
>> apart from looking cooler to most people. Having something that
>> people can immediately interact with is very powerful to convince
>> people.
>
> To be honest I think I do underestimate the power of hypermedia. Now

:-)


> from a technical point of view, I want to implement it because I
> want to offer the best quality design. But from a commercial point

What makes it the "best quality design" if it doesn't solve some problems?


> of view, listening to consumers, I don't get the question to
> implement Hypermedia very often. The benefit of a web API over a

Of course not. You also don't get asked very often to implement data
interchange over TCP/IP. It's an implementation detail. A design choice you
as the developer have to make. Your customer wants a solution for his
problem. He doesn't want an API. That's something we engineers unfortunately
often forget.


> static CSV (or, in the Dutch Open Data landscape, often much worse
> static files) is indeed that it's easy to consume and you don't have
> to download (and parse, which might be quite annoying to do with
> other formats) the files every time the data changes. In most cases

Isn't it easier for a user to browse the data than having to read
documentation that tells them how to construct URLs to access the data they
are looking for?


> with Open Data consisting of tabular data, people just want to refer
> to a single resource. For example to find area information based on

Right. And often people want to share that information with other people.
Simplest thing, copy the resource's URL into an email or IM message and send
it your friend. She clicks on that link (that means she uses a hypermedia
control) to access that resource.


> postal code or car information based on car license number. I don't
> see many people page through collections very often. If they do

Simple links as used for paginated lists are the simplest hypermedia
control. Nothing stops you from adding more sophisticated ones that allow
you to filter a collection to realize the use case above.


> that, they probably want to harvest all data, and that's exactly why
> we are not offering a CSV download.
>
>
>> I don't know how your process looks like and what your clients
>> expect. Do you write documentation for those JSON-based APIs? Do
>> you provide clients in the form of SKDS, libraries or API consoles
>> to access them as well?
>
> I am huge fan of RAML (http://raml.org) myself. It gives us the
> opportunity to design the API responses while programming apps
> against it (using the Mulesoft API design tool), so we can discuss
> and change the responses together with our app developers instantly
> using mock responses. As it's valid YAML, it's easy for machines to
> read and thus parse documentation, consoles, etc. from.


Yep, the tooling around RAML is nice. We don't have such tooling yet as we
don't have the resources that MuleSoft has. But I'm convinced that Hydra
allows the creation of much more powerful tooling than RAML does.


> And since we just provide RESTful JSON API's, SDK's and clients are
> built-in for the majority of programming languages our communities
> use ;-)

What do you mean by "built-in"?

I'll include your second mail directly into this response

On 6 Aug 2014 at 17:55, Dimitri van Hees wrote:
>>> 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!?
>
> It is, but finding or defining the right links (for example on
> DBPedia) still takes additional time. Besides, I still experience a
> lot of people who are complaining about the payload. (I don't agree
> with them though!!!!)

Nothing prevents you to define your own vocabulary. You can add mappings to
other vocabularies (or change the context) later on. JSON-LD doesn't mean
you can't be pragmatic when designing your APIs. You just need to be aware
of the trade-offs you make.


>>> 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"
>> }
>
> I apologize for not knowing that feature, I didn't know that was

No need to apologize :-)


> possible. But there are 2 things why I wouldn't prefer this
> approach: 1) a consumer would need to parse the @context to get the
> right links and

Well, if you process it as JSON-LD, you have to process the context. It's
like saying you want to render an HTML file but don't want to process the
<head> section.


> 2) I love the use of static external context files
> as it makes development less complicated ;-)

So? This context can, just as any other context, be moved to a separate
file.


> A question I still have about this example is: why isn't it defined
> that London is a 'http://schema.org/City'? Perhaps I am doing it

You mean in the context? Because in the context you can only define the
datatype of string values of a property. London is not a property, it is a
class. This has to do with RDF's data model that underlies JSON-LD.

In case you have some time, reading

  http://www.w3.org/TR/rdf11-concepts/

might clarify this. At least it helps you to understand the data model
better. Using it's terminology, @type in the context sets the datatype of a
literal, just as @language in a term definition sets the language tag of a
language-tagged string. @type in the body of a JSON-LD document is an alias
for rdf:type if it appears on an object *without* @value. If there's @value
on that object as well, @type again sets the datatype of the literal in
@value.



> wrong because my only reference at the moment is Allegrograph's
> visualization tool Gruff which gives each 'type' an own colour so I
> can see which nodes area actually cities. I don't see the @type
> attribute being used often however, so does this mean it's
> completely useless without visualization?

No, it's not completely useless. It is just a consequence of the fact that
in RDF (and JSON-LD) the subject of a triple can't be a literal (think
string). So

   <resource> :property "value" .
   "value" rdf:type xsd:integer .

is invalid. To allow "value" to be typed, RDF splits literals into three
components [1]: lexical form ("value"), datatype IRI (xsd:integer) and an
optional language tag. You express this as follows in Turtle:

   <resource> :property "value"^^xsd:integer .

In JSON-LD it is

  {
    "@id": "resource",
    "property": {
      "@value": "value",
      "@type": "xsd:integer"
    }
  }

which can be simplified to

  {
    "@context": { "property": { ... "@type": "xsd:integer" } }
    "@id": "resource",
    "property": "value"
  }

You, however, would like

  {
    "@context": { "London": { ... "@type": "schema:City" } }
    "@id": "resource",
    "property": "London"
  }

To expand to

  {
    "@id": "resource",
    "property": {  <-- London is not here
      "@id": "London",  <--- note @id here, not @value
      "@type": "schema:City"
    }
  }

That simply doesn't work. A processor wouldn't know what you had in mind
when you wrote it. You would need to introduce additional keywords to make
it work the way you want.


Hope this clarifies it


[1] http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal


--
Markus Lanthaler
@markuslanthaler

Received on Friday, 8 August 2014 09:37:01 UTC