Why Hypermedia APIs Matter
You have probably heard recent ramblings about Hypermedia APIs, or HATEOAS, and you completely ignored it because it doesn’t seem to matter. Well, I am here to tell you why it matters. Hypermedia APIs are all about building APIs that allow clients to adapt to changes.
Say you build an amazing REST API for your awesome app. People read your API docs and start using it because, well, it’s amazing. Then, your application evolves. You want to change things, but you can’t, because clients are hard-coded to your API docs. You now have 3 options: 1) avoid changing your app, 2) change it and break existing clients, 3) fork your API and maintain two versions while you wait for old clients to update to the new version. All three of these options suck.
You thought you built a REST API by using HTTP verbs and real URLs. That’s not REST. Read Roy Fielding’s rant REST APIs must be hypertext-driven. Roy knows a thing or two about REST; he kinda invented it.
If you want to build APIs that can adapt along with your application, then you need to learn about Hypermedia APIs. Many people are writing great resources about what this hypermedia stuff is all about. I don’t need to duplicate their effort. If you want to learn how to build adaptable APIs, then start with Steve Klabnik’s Hypermedia API reading list.
There is currently a severe lack of example Hypermedia APIs. I am working on the Speaker Deck API and hope to have at least one good example soon.
I am Brandon Keepers, and I work at