How to Build Hypermedia APIs with JSON-LD and Hydra

“The benefits for developers in adopting Web APIs are an easy way to enrich functionality, simple and quick to Integration, and leveraging brand strength of established partners,” said Manfred Bortenschlager of 3Scale.

However, Web APIs—or Web application programming interfaces—can be a challenge both for you to create and for your developer customers to understand. This is why Markus Lanthaler, software engineer at Google, created JSON-LD and Hydra as a combined solution to the challenges presented by Web APIs.

Lanthaler says the normal process for creating Web APIs is to

  1. Define the URL structure.
  2. Expose your objects as JSON.
  3. Write your API Documentation.

He says that, if you follow that formula, as soon as you announce your Web API, you are going to get less-than-desirable feedback almost immediately. “There is quite sure, quite quickly, someone who finds out that this is not RESTful. Some smartass [sic] typically comes out and says, ‘You have to use hypermedia, otherwise it’s not RESTful. You did it wrong.’ Normally those people can’t explain why you need to use hypermedia or what hypermedia actually is,” but, until you use hypermedia, you can’t say you have a RESTful API.”

But does it really matter? Are you required by law to have a RESTful API? “I would argue in quite a few cases, it doesn’t really matter at all. If you’re just building a Web API for your own mobile application, it doesn’t matter. If you’re building a single-page web application, it doesn't matter either because you are the only consumer of that web application.”

“It does matter, however, if you want to build a Web API which is usable by other people as well. And especially if you want it to be usable by other people without having to talk to them too much, without having to do partnerships, without having to write SDKs yourself. So if you really want to build something that is across the web, that is general enough, that is stable from a consumer’s point of view, then you should invest a bit more in the design of a Web API.”

However, Lanthaler says that doesn’t need to be a huge time commitment or tech commitment. He is in the process of developing JSON-LD and Hydra to make the creation of Web APIs much more streamlined and developer friendly. This post follows up his APIcon UK presentation to talk about how to create simple Web APIs while always prioritizing that “The consumer is king.”

Use JSON-LD to expose your objects with context by mapping to

Lanthaler started out his talk by recommending not to worry much about URL structures. “Do whatever you want, as long as your Framework works better with that specific URL structure, it’s fine. Just do something that you don’t have to change immediately,” which also means don’t include too much information in the URL.

JSON example

The next step is to expose your objects as JSON in a way that the message is self-descriptive and can stand alone. In the traditional process of Web APIs, “We get back JSON. This is easy to understand for a human but for a machine it isn’t clear what this means.” He says the objective needs to be, “What we would like to do is to transform this mess back into something that is understandable by both a machine and a human. To make it as simple as possible but nevertheless to give the machine the information to make sense of it. To be able to generalize the solutions to reuse code across projects, etcetera.”

“What we need is a shared vocabulary, which both parties understand—that the server understands and the client understands. If they talk the same language, they can understand each other,” Lanthaler uses the business world in general as an example, where most default to the common language of English. definition of concept is the common language that Lanthaler suggests because it was created and is understood by the four major search engine providers: Google, Microsoft, Yahoo and Yandex. is a collection of uniform Resource identifiers or URIs that in this case are the URLs, “so that we can de-reference them so that we can get the definition of those concepts if we don’t understand them [all] by just looking at them.”

Then, in order to translate those URIs into a context that a machine can understand as well, you use JSON-LD, a set of conventions which helps to make JSON messages with an unambiguous and well-defined meaning. This is done by keeping the human-friendly document body exactly the same and then mapping it to URLs by adding a context in JSON-LD.

Convert string token before and after

One way to make the ID more useful, is to convert the string token to a full URL by replacing id with @id. JSON-LD also takes care of mapping common conventions like @type. will also allow you to define more custom conventions like start and end dates, clarifying them for both machines and humans.

Reference to context

If you don’t like the @ symbols, you can also map the token id to the @id. This way the document reverts back to looking simple for all humans, but you’ve also translated it for machine-readability. The idea is that you can reference to context in separate documents or by referencing the HTTP link in the header, in an effort to be sure to keep your Web API very clean and clear for human eyes.

This also decouples your internal objects from your external representations. Bonus, if you use JSON-LD for things like events, Google can easily extract that information for its Knowledge Graph, with a link back to your website. A common real-world implementation is when airlines  embed a block of JSON-LD within their emails so that then you can easily view flight status and go right to check-in, all from inside your Gmail inbox. This is also what drives the always surprising ability to  search for “my flights” and their current statuses plus passengers show up as a result, even with downloadable boarding passes.

JSON-LD as used in Gmail, Flight Status

As long as the mapping is still the same, the data is still the same. This way developers can make use of your Web API without having to change anything, while still making sure machines can understand it all.

Be sure to read the next API Design article: Netflix's Falcor is a Data Fetching Gift to Developers