Link to the essay, by Kieran Potts
The Essence
REST is often incorrectly used to describe what is actually an HTTP API. Why is this a misnomer? The original academic paper that introduced REST emphasizes the importance of hypermedia. Therefore, a truly RESTful API must be a hypermedia API.
What is Hypermedia?
The World Wide Web is an example of a RESTful platform. It requires an entry point, such as a domain name. The server’s response must list all the actions that the client can take, both at the beginning and as the interaction progresses.
Does a typical CRUD API follow these principles? Or does it rely on an OpenAPI specification or external documentation for the client to understand how to interact with it? If the latter is true, then it isn’t RESTful.
A ‘You are the Hero’ Book Analogy
Think of a ‘You are the Hero’ gamebook. It starts by explaining the rules of the game and how to handle different scenarios. When you begin the quest, the book presents a situation and lists possible actions with references to the relevant pages. You choose an action, turn to the page, and continue until you reach the end or hit a roadblock.
This is similar to how hypermedia works. The gamebook is your entry point, the rules are the protocol, and the quest items are the responses with actionable choices. With just the gamebook, you can navigate the entire quest.
Final Thoughts
APIs are often classified by their protocols, not by their architecture. So, it makes sense to call traditional REST APIs “HTTP APIs.”
Hypermedia requires a protocol that provides a clear way for smart clients to navigate. For the web, HTML serves as this guide for humans, with browsers acting as interpreters. But what about machines consuming hypermedia APIs? Web crawlers already navigate the web and understand its structure. So, do we need a new protocol? HTML over HTTP may be too verbose for machines, as it’s designed for humans. The challenge might be to find a more concise, machine-readable format.