RE: "Plain JSON" vs Hydra

> 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 of view, listening to consumers, I don't get the question to implement Hypermedia very often. The benefit of a web API over a 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 with Open Data consisting of tabular data, people just want to refer to a single resource. For example to find area information based on postal code or car information based on car license number. I don't see many people page through collections very often. If they do 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.

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

Received on Wednesday, 6 August 2014 15:43:06 UTC