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.
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:
- What happens if you invoke an operation.
- Why you might want to invoke that operation.
- 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.”
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.
“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:
- Focus on the data modeling. Look how other people already mark it up and for something that exists already.
- Work to make everything machine processable in order to generalize solutions and better automate things.
- Stick to the standards.
- All of this will enable broader adoption and the ability to reuse other people’s work.
Images courtesy of Markus Lanthaler