Call us Call Us (111) 234 - 5678

info@linkeddataorchestration.com

On APIs, JSON, Linked Data, attitude and opportunities

I’ve been meaning to revisit some of the things i’ve been writing about and getting feedback on lately – APIs, the JSON vs. XMLnon” 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?

Reinventing the wheel? Source: Jake Fleming

Reinventing the wheel? Source: Jake Fleming

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.

This is NOT Rocket Science. Really. Source: BJ-O23

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.

Post Tagged with , , , ,

8 Responses so far.

  1. Martynas says:

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

    Why is that? This is exactly what I would recommend. How else are we gonna get to the Semantic Web?

    • George Anadiotis says:

      Thanks for the comment Martynas.

      In one sentence: because in the end of the day it’s not about getting to the Semantic Web (or being compliant to any grand vision or set of guidelines etc), it’s about getting the job done. And to be realistic, you’d be hard pressed to get a dev team today that has the skills to start designing and implementing something like this. And in many cases, you probably would not even need this. And for certain scenarios, it would just not work.

      That said, there are cases where it would make sense, and it would work. But i don’t think it’s the “average Jo” web app.

  2. pete gamache says:

    I think HAL makes a very good case for itself when compared to Collection+JSON, JSON API, Siren, JSON-LD, Hydra etc. For me, this centers on three points.

    Most importantly, HAL replies look like replies from a plain ol’ JSON API, with two extra fields. This means people not using a hypermedia client — basically everyone in the world for the next several years — may use the API with zero friction. They don’t need to unpack attributes and objects from various container fields; they just need to ignore _links and _embedded. In my opinion, HAL is the format most suitable for a “transitional” hypermedia API. JSON-LD is good about this too, but not as good.

    HAL doesn’t make assumptions about your API’s philosophy. It’s there to provide hyperlink and embedded object support, period. Where other hypermedia formats try to capture more semantics, HAL essentially gives the computer everything it needs to connect the interpipes and leaves the rest to the API documentation. This “just enough” design means that it’s equally applicable to 100% REST APIs and RPC-over-JSON abominations. JSON-LD is good about this, but not as good.

    And HAL, much like JSON itself, has the attractive quality that you can explain all you need to explain about it on a note card. This means it is very simple to write a client for HAL. This is why, even in the desolate client space of today, there are a dozen libraries to consume HAL. JSON-LD is not as good about this.

    For me, I don’t think the “rough consensus” part of “rough consensus and working code” is clear, so I am leaning on the latter.

    Full disclosure: I wrote a hypermedia client for Ruby called HyperResource, and HAL is the first format it supports. https://github.com/gamache/hyperresource

    • George Anadiotis says:

      Pete, thanks for taking the time to read and provide such a detailed answer.

      I do understand your rationale, and personally i think your 3rd point bears more weight than the others. I see HAL as the low-hanging fruit at the moment, so i would not want to whine too much about all the could have beens. Hence the closing paragraph – you gotta start somewhere.

      I’d like to get back to your first point though, but i need some more time for this which i do not have atm. Will do asap.

    • Pete, could you elaborate a bit on your first point:

      “Most importantly, HAL replies look like replies from a plain ol’ JSON API, with two extra fields. This means people not using a hypermedia client — basically everyone in the world for the next several years — may use the API with zero friction. They don’t need to unpack attributes and objects from various container fields; they just need to ignore _links and _embedded.”

      I’m especially interested in why JSON-LD is “not as good” as HAL in that regard. If that’s really the main design goal, you should simply use HTTP Link headers instead IMHO.

      Btw. I fully agree with you that HAL has more tooling at the moment.

      Disclaimer: I’m one of the core designer of JSON-LD and co-authored/-edited its specifications.

      • George Anadiotis says:

        Markus, thanks for your comment – that was going to be along the lines of my own reply to Pete’s first point actually.

        I wanted to research this a bit more as i do not have that much of a hands-on experience with JSON-LD, but coming from you i take this as definitive.

      • pete gamache says:

        Hi Markus,

        JSON-LD is simply a richer format than HAL, and that richness comes at the cost of simplicity of output. As a core designer of JSON-LD, I am surprised you would argue this point! JSON-LD has several different output serialization formats, and more features than you can shake a stick at. Additionally, “simple” data and JSON-LD structures are commingled, forcing users who are not using a JSON-LD client to be aware of many JSON-LD rules.

        In contrast, HAL supports two features — hypermedia, and embedded resources. The separation between “simple” data and machine-readable HAL annotations is clear, as all the bits which are designed for machine consumption are segregated into the “_links” and “_embedded” fields. This means the end user needs to know very little in order to use a HAL API outside a hypermedia context.

        Could many of the same things be accomplished with Link headers and a plain JSON API? I suppose so, but I have found value in expressing hypermedia as part of a response body rather than as an auxiliary header. It makes using the data more convenient — at least for me it has. One notable example is that of a resource containing embedded resources, whose hypermedia would not be easily expressible in headers.

        From a standpoint admittedly ignorant of the JSON-LD team’s actual goals, I feel like JSON-LD is trying to be a perfect hypermedia and linked data format, whereas HAL is designed to be immediately practical for providing basic hypermedia support. I have had great success using HAL in a production environment, and for my somewhat simple API needs, I doubt JSON-LD would have been a better call. I imagine Amazon’s thinking is along similar lines.

        Thanks for the comments!

        • Too bad you aren’t notified when someone replies to a comment. Anyway, I stubmled across this post again so I saw Pete’s reply.

          I never said that JSON-LD isn’t the richer format but you can certainly make it look like completely idiomatic JSON. In fact, you can hide all the JSON-LD stuff in a HTTP Link header if you want. That’s the reason why I asked you to elaborate on your statement

          “Most importantly, HAL replies look like replies from a plain ol’ JSON API, with two extra fields. This means people not using a hypermedia client — basically everyone in the world for the next several years — may use the API with zero friction. They don’t need to unpack attributes and objects from various container fields; they just need to ignore _links and _embedded.”

          … “JSON-LD is good about this too, but not as good.”

          In your reply you seem to talk about a completely different aspect, i.e., that there are many ways to serialize the same data in JSON-LD. Yeah, that’s true. JSON-LD does much more and that inevitably introduces variability (if you want to keep it human-readable). There’s however a standardized JSON-LD API (and implementations thereof in all major languages) which eliminates that variability.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>