How to Build Hypermedia APIs with JSON-LD and Hydra

Speak Hydra to describe a RESTful Web API

There’s no doubt that API documentation is the most important thing to the developer experience. But that’s not because it’s super fun to read nor to create, but because it shows the developer what she can do with your API. Lanthaler created Hydra to transform the often tedious API documentation process into an interactive, intuitive experience for humans, that is still machine readable.

According to the official website, Hydra is an effort to simplify the development of interoperable, hypermedia-driven Web APIs. The two fundamental building blocks of Hydra are JSON‑LD and the Hydra Core Vocabulary. The Hydra Core Vocabulary represents the shared vocabulary between the server and its clients.

Hydra inline description of an API

The main idea is that instead of having to jump back and forth with the all-important API documentation, with Hydra, you can describe it in-line for both the clients and servers, so they don’t have to read that documentation. It explains:

  1. What happens if you invoke an operation.
  2. Why you might want to invoke that operation.
  3. How to invoke that operation.

“Simply speaking, it’s a way to guide clients through your Web API,” Lanthaler said. “And in that way the machine can read the documentation for you.”

Expose class map to URL with PHP and Symphony2

This is an example in PHP and Symphony2, but these sub-collections apply with other languages too

You can then go into even more detail for the machine, while keeping it simple for the naked eye by defining your own collections and subcollections, all the time exposing the class and mapping it to URLs.

You just have to make sure you describe the operation of what this controller actually does, mapping it to the URL and explaining what is the data the client should expect to get back.

Describe operation controller

“And in that way, really everything is really taken care of. You don’t have to think about JSON-LD serialization. You don’t have to think about how to describe those things with Hydra. That can all be automated in the backend. You just have to do those few mappings to yourself,” Lanthaler continued.

He says that the big advantage that comes with this is that you can browse the Web API, not having to build a client, since a generic client already exists.

The Hydra Console works using the following steps:

  • Working like a browser, you plug in a URL.
  • Hydra goes and retrieves your JSON-LD document.
  • It fetches the documentation for you, taking it directly from the URl.
  • If there are operations related, the Hydra Console will offer a popover so the developer can select the operation she’d like.
  • When you want to create a new event, the Hydra Console has enough information to render a form for you.

“It means that your clients and customers can really start playing with your Web API while you’re [still] building it. You don’t have to wait for an SDK to be developed or a mobile application or a demo API console. You can really start to play with the API immediately, Lanthaler said. “And also non-technical people can start to evaluate whether you actually implemented what they wanted to have.”

This way you can get your Web API out there faster, being used faster, and simply making it easier to use.

Final tricks for easier Web API design

Web APIs don’t have to be harder but they do take a bit more forethought about design and what you would like to achieve. Follow these tips:

  1. Focus on the data modeling. Look how other people already mark it up and for something that exists already.
  2. Work to make everything machine processable in order to generalize solutions and better automate things.
  3. Stick to the standards.
  4. All of this will enable broader adoption and the ability to reuse other people’s work.

Join the Hydra Community to become involved in the evolving art of Web APIs. Check out the different technologies behind Hydra.

Have you worked with JSON-LD or Hydra before? Or do you have a better way to create and expose Web APIs? Tell us about your experience below!

Images courtesy of Markus Lanthaler

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


Comments (2)


It's often states that JSON is more readable than XML, however in reality is only perhaps slightly more readable - so I don't think too much time should be spent making the JSON look "simple for all humans".

Humans can always use a tool like to transform the JSON into something fully readable.


A framework makes really easy to create JSON-LD/Hydra/ API:

It provides a data model generator using types and an API system leveraging automatically generating a JSON-LD and Hydra API doc as well as a human readable doc.

It is also able to manage data persistence and validation, pagination, HTTP cache, authentication (using JWT or Oauth) and is compliant with thousand of existing Symfony bundles (API Platform is built on top of this PHP framework).