2 July 2012
The Web is a Hypermedia API
If you’re struggling to wrap your head around Hypermedia APIs, the first thing you need to understand is that you actively use one every day. Unless you were just handed a printout of this article, you are using one right now.
The Twilight Zone
Imagine that you live in an alternate dimension. You want to do some online shopping, and you have just received the latest Amazon.com client. You fire it up and do a product search for “Three’s Company DVDs”. All of the product data comes down the wire. We have the names, brands, and prices of the twenty most relevant “Three’s Company” related products. After the client gets the data, it goes to work! It builds all of the urls and applies them onto all of the product data that came down, so that you can click on the DVD set that you like. Wait, no! The client doesn’t do that!
To anybody with a passing amount of knowledge about how to build a website, the situation above seems ridiculous. In this dimension, we have a web browser that knows how to read a representation of data called HTML, and render and activate the links that the server provides in that document. The server defines where the resources reside, so naturally, the server provides the links to those resources.
We Didn’t Know Any Better
My alternate universe attempted to describe a scenario in which the web that we know and love operates like an API that I designed last year. I think a lot of people design APIs in this way, i.e. they do what they need to do right now. They provide some locations on their server that allow a third party to read or write to some resources. That doesn’t sound so bad, right? An API totally needs to do those things, but it needs to do a little bit more. APIs are by definition publicly available, they invite themselves into a realm of of other people’s stuff that you no longer have total control over. As such, some forethought needs to be given to design up front. APIs that only provide the resources, and not the locations to next resource, are taking the short view and are introducing big problems for the future evolution of your system.
The fatal flaw will smack you soon enough. When you rolled out the API, you promised all of the people, in your meticulously crafted documentation, that the resource they want is available at location x. They, in turn, built clients around that promise, and now you badly, badly need to change that location to y. Go ahead and update that documentation and see how much it helps. Best case scenario is that you built the client, and now you have to get everybody to update it before you can get back to doing anything productive on your end. To quote Steve Klabnik, “People are really good at screwing themselves over in the long term”.
Robots Like to Surf The Web Too
So what’s the solution? Let’s bring it back to the web to understand how we can address this. Grandma has a home page with a link people can click on to see pictures of all of her perfect grandchildren. Six months later Grandma finds a cheaper site for hosting those pictures and wants to put them there instead. As Grandma’s faithful webmaster, you update the link on her homepage to point to the new photo sharing site. Does the whole world need to update their web client now? Of course not, the link to the next resource is defined and provided by the server in the HTML it sends down, and that link just changed. I think the best short description of an API I’ve found is in Ryan Tomako’s article “How I Explained REST to My wife”. Paraphrasing, an API is an interface for machines to use the web just like people do. APIs that don’t employ hypermedia are basically jerks that are saying to clients, “I know where to go next, but I’m going to make you guess how to get there anyway.” With a Hypermedia API you force the client to know the location of exactly one resource, “Home”.
So applying Hypermedia to APIs provides solutions, but also really transforms the very nature of the interaction into something much cooler. APIs whose resources link to other resources become “engines of application state”. Every resource exposes it’s current state, and the paths that you can take to create, interact with, and shape it. When an API describes to you how to interact with it, clients can be designed in a static way, reactively handling changes from the server.
Hypermedia APIs in Practice
So how do you go about achieving this? Unfortunately, I have little practical experience to share. I understand a few things. People who talk about REST, talk about nouns and verbs. All APIs provide the nouns, Hypermedia APIs provide the verbs too. In addition to the data the APIs traditionally provide, at every step of the way they need to describe, with links, 1) where to start 2) where you are, and 3) where you can go next.
There are definitely some best practices around things like content negotation and media types that you can read up on, but I gather from Chris Moore that it’s still the Wild West for Hypermedia design. Apparently making more effective use of HTTP Headers is good design, and you want to give some thought about your content format, because types like JSON and XML are not implicitly hypermedia aware, i.e. they have no baked in concept of links.
Acknowledgments
While I’m talking about what I do know, maybe it’s a good time to mention where I learned it. The impetus for all of this was this talk given by Steve Klabnik at the most recent Cincy.rb meetup, just a couple weeks ago. Steve’s done a ton of writing and speaking around this subject, just google him or pick up his evolving book, “Designing Hypermedia APIs”. The talk is an overview of what Hypermedia APIs are, why they’re important, and their philosophical implications. Thankfully, Steve gives us permissions to stop worrying and fighting about REST and focus on cool stuff. For the Rails folks, Steve recommends two gems, active_model_serializers and rails-api
I also highly recommend this video presentation by Jon Moore, in which he actually demos a static client. If this link between Hypermedia APIs and the web as we know it is still nebulous, this video will solidify it for you. I really like the way Jon explains things and boils down the dissertation language, translating a block of Fielding into “You do stuff by reading pages and then either following links or submitting forms.”.
For some deep reading, I’ve heard people recommend “Building Hypermedia APIs with HTML5 and Node”. Don’t worry if you’re not a node programmer. I also want to give a shout to Chris Moore, who’s been our resident Hypermedia API pusher, and Sean Allen, who’s been harping to me about REST since before harping about REST was cool.
Conclusion
If you need inspiration in understanding hypermedia APIs, look no further than the web. The architecture and protocols for the web were designed by really smart guys who already figured this stuff out a long time ago and can be applied universally. Once I started viewing APIs through the lense of the web I know and love, it actually seems completely wrong to design one in any other way.
