RE: "Plain JSON" vs Hydra

>> 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?

Well... It's like optimizing a site's performance from 0.05ms to 0.04ms. From a technical point of view I want the best of the best, but I can't sell it (so will have to do it in the evening hours ;-))

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

There is a difference between 'consumer' and 'customer' in my opinion. Indeed, customers don't ask for API's. But consumers are, for example, developers who are using our free Postcode API. We receive tuns of feature requests but none of them asked for Hypermedia (yet). Still as stated above, we want to implement it, just in case.


>> 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?

Depends on how you define 'user'. If the user is the same 'consumer' as I mentioned before, then they are used to RESTful URI's which speak for themselves if proper naming convention is being used. This reminds me of a discussion I've had about code documentation. When using human readable method names (like in DDD), it doesn't make much sense to repeat the name of the function in a doc block in my opinion. I'm not a huge fan of commenting 'Gets the ID' above a 'getId()' method. What I am trying to say is that if we design a Postcode API which has an entry point at api.postcodeapi.nu then it should be clear that api.postcodeapi.nu/postcodes/1234ab if the resource and /postcodes is the collection.


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

I think people only share traditional HTML pages to be honest...


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

I agree.


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

I think they are both different things. RAML Is just a way to design the API. So I think the Hydra responses should be designed with RAML. Then if the responses are finished, you can indeed choose to generate the documentation and client applications from the API itself.

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

json_decode(file_get_contents()) in PHP for example. Or in one of the many libraries and frameworks out there dealing with RESTful JSON API's.


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

Let's say I have a list of cities and I want to show the weapon of each city in my Angular app using DBPedia. Then an array with 'label' and '@id' (to the DBpedia page) is a lot easier to use then to parse the context.


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

If it's static yes. But if it's dynamic then I have to dynamically generate the context file everytime the content changes (when Berlin is being added for example). Of course it's possible, but I don't like it.


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

Thanks for the explanation. The response that suits me most is this:

{
  "@context": { "city": { "@id": "http://schema.org/homeLocation", "@type": "@id" } },
  "city": { "@id": "http://dbpedia.org/resource/London", "@type": "http://schema.org/City" }
}

Dimitri





>
>

Received on Friday, 8 August 2014 11:20:54 UTC