I’ve been meaning to revisit some of the things i’ve been writing about and getting feedback on lately – APIs, the JSON vs. XML “non” debate and Linked Data. My focus was going to be on JSON-LD as the low-hanging fruit of Linked Data, and this week some news came out that gave me the perfect opportunity to do this:

Amazon has released a new API, the AppStream API, which allows you to programmatically manage applications hosted on the Amazon AppStream platform. Amazon chose to build this API with the HAL media type. HAL is a minimalistic hypermedia enabled media type for building machine-to-machine APIs.

InfoQ goes on to state that “this vote of confidence in hypermedia via HAL from one of tech’s biggest companies should hearten hypermedia enthusiasts”. But first things first. What is HAL? And what is a Hypermedia API actually?

According to Steve Klabnik, the person who coined the term, “A Hypermedia API is one in which the architecture of the API is similar to the architecture of the world wide web”. Ok, that sounds cool. And by taking a look at this presentation that introduces the topic, i found it makes a lot of sense. So let’s go for Hypermedia APIs indeed, if the pros outweigh the cons for your use case. And as for HAL, well, this is one of the possible Hypermedia media types: in essence, JSON (or XML) plus links.

So HAL = REST + Links in JSON, basically. And this is where some folks might begin to wonder: so what does HAL give you that “normal” JSON API doesn’t? URIs? Apparently. Don’t get me wrong, i do like the idea of links to discover resources etc as much as the next guy. More than that even, i think it’s great. That’s definitely a good way to go, the web was built on that etc.

Except for one thing: it’s been done before, touted by the inventor of the WWW no less as “the web done right”, and it’s called Linked Data. And you can do it using JSON. And it’s a W3C spec. And there’s a bunch of open vocabularies out there you can use to add more than links – semantics. And you can even do it on top of your existing application’s relational db (and serialize the output in JSON). Heck, soon you should even be able to use an actual query language (SPARQL) to query your (standardized) JSON in your store in a (standardized, expressive and efficient) way.

So, what’s wrong with that? And why not use JSON-LD for this? Your guess is as good as mine, but mine would be that it’s a matter of attitude and perception more than anything else. And in that respect, i am sympathetic. The Semantic Web is often dished as being too complex, cumbersome, useless, etc. But while i will certainly admit there are some elements of truth in the criticism (especially the group-think aspect), i think that for many people this has taken somewhat religious proportions, thus making them refuse to see the obvious and even consider this technology where it makes sense, and re-inventing the wheel instead.

While i would not recommend building your average web app using an ontology and a triple store as opposed to a plain old schema and RDBMS, i can attest from my own experience that it really does not take much to get an API up and running using Linked Data technology in a very short time. We did that back in 2009, with less mature tools than the ones out now. Developers with a good working knowledge of SQL had no problem catching up with SPARQL within a few hours and the mapping is no nuclear science either.

I do not want to get religious about this myself. I do understand the issues involved with Linked Data adoption, technical and non-technical alike. And to end this note in an optimistic tone, i think that getting used to this kind of approach will eventually lead to reconsidering the use of Linked Data where it makes sense. So, a big thumbs up for Hypermedia APIs, for HAL, and for Amazon swithing to that. Let’s see what’s next, and if this is indeed a transitional stage.