DHH posted a rant on hypermedia APIs earlier today, and we feel like he got a lot of things wrong. We’ve seen that the view he’s expressing comes from an incomplete understanding of the ideas that both defined the web in general, and that are pushing the current movement in API design.

In general, hypermedia in APIs is when resources provide links to other resources as part of its representation. “Proper” use of a REST or hypermedia API generally requires you only ever initiate communications with the API from the root (https://my.api.example/ versus https://my.api.example/some/other/url). From there, every response from the API will then contains links to other resources, often with a relation to explain how each resource relates to the next. In this way, you never guess a URL - you are always given it.

In theory, this lets the API structure evolve over time without breaking older applications, and allows applications to do new things without being changed. In design pattern language, we would say that this allows client and server to vary independently.

DHH seems to be arguing the following:

• Hypermedia doesn’t improve discoverability, documentation does, as there’s no guarantee every piece of data can be found.
• Bookmarking URLs destroys the benefit of using hypermedia, as you’d be saving a URL that might change.
• A single API client for many APIs is a myth we should stop chasing after.

Discovery in Hypermedia

For most data APIs, discovery is the core benefit of hypermedia - to communicate all related data points in your representations. These data points need to include not only individual data points but also collections of data points, or any other related resources. APIs that use hypermedia but don’t link to all possible locations are broken.

Let’s use search engines and crawlers as an example. If you have a page in your website that nothing links to, how can they find it? With no link to it, they can’t. The solution is a sitemap. This is an API, with a standard, using hypermedia, solely to enable discovery.

Secondly, I believe developers should need to read little or no documentation to start playing with an API. We’re inquisitive folk by nature, and enjoy experimenting with technology. Hypermedia enables this experimentation in a lightweight, convenient way. DHH suggests good API docs explain all possible attributes of a resource. The API should too. An API that someone can dive right into without documentation just to play is a good API.

Bookmarks

Saving API URLs is something I’ve thought a lot about over last few years. People are definitely going to do it, and DHH does make a good point that it can break down the benefits of hypermedia.

But there’s a simple and easy solution to the whole problem. There’s a ‘bookmark’ relation. A link with this relation could be a URL like https://my.api.example/find?type=project&id=5 or https://my.api.example/urn_url_converter?urn=urn:api.example:project:5, providing a universal way to locate an individual resource in an API where URLs can change.

The query string could really be whatever you want to uniquely and permanently identify the resource. So when I move the project resource from being at /projects to being under a User at /users/1/projects, that bookmark URL can still work. And when I rename Contact to Friend, I can still get you where you want to be.

And bookmarks will break, as they do on the web. When they do, hypermedia enables us to get back to where we want from a fixed, known starting point. Without it, code needs to be changed.

Universal API Client

Is it a myth?

It seems to work extremely well for the web - the largest and most successful application of RESTful concepts in the world. Hint: Your browser is an API client, HTML resources are hypermedia/HATEOAS in action, and javascript is code-on-demand to enhance the experience.

The movement towards REST/hypermedia in API design is an attempt to apply the concepts and techniques used to achieve the massive success of the web to the API world. Dismiss the hype, sure, but not the concepts. We, as a community, are still trying to figure out the right way to apply some of those.

As an example of where we actually do have some answers, well documented and consistently used custom media types can allow an API to easily understand “the difference between Flickr photos and Basecamp projects”. Media types help drive the web, so why not APIs?

Final Thoughts

I can’t help but wonder if DHH’s post is a sign that we may be moving into a Trough of Disillusionment with respect to REST/hypermedia APIs. That’s actually very exciting to me, because it means we’re one step closer to sitting on that shiny plateau. That’s probably where the mythical universal non-browser API client has the potential to rear its beautiful head, and once again change the way we interact with information forever.