Curmudgeon's Guide to REST
This is an opinion piece about the state of APIs on the web. Caveat emptor.
Ever so often the phrase “REST API” is used to advertise a service, there is someone who is irritated that it is not really RESTful. Indeed, REST is misused by people who don’t understand it or simply repeat false information. The common pitfalls of APIs marketed as RESTful are not trivial to solve, and matter much more than one might think.
If you’ve ever used a web API out in the wild, chances are that you’ve had to read some technical specifications, considered out of band information, in order to use it. This is usually because there’s no mechanism of control or links in the payload, either for humans or robots. If links are present, they are often not encoded as links and rely on clients to construct URIs. What is typically the case is that API design is bike-shedded (or worse, not invented here). Clients have to assume, sometimes incorrectly, a priori knowledge of what exists on the server.
The widely implemented solution to documentation goes something like this: use comments and annotations in implementation code to generate documentation in a serializable format (such as Swagger, RAML, etc), or worse, have a human update technical documentation manually. The problem with either approach is that they rely heavily on humans to do busy work. This busy work is extended to maintaining API-specific clients in multiple programming languages, or else pass the busy work on to consumers to write their own clients. APIs on the web are in a fragmentation Hell in which every implementor acts like they are a special snowflake, deserving of special attention to the intricacies of their particular syntax.
Web APIs are usually delivered through HTTP (Hypertext Transfer Protocol). What is crucial to the concept of hypertext is that it contains hyperlinks, and if you are reading this, you probably followed hyperlinks to get here. The media type “HTML” facilitates the following of hyperlinks in a document. We take this for granted, as even non-technical users are able to follow links on a page and know where they are based on the current URI.
What most people pass off as RESTful is using URIs and HTTP verbs, but this is simply not enough. There is a better approach, though it is not easy: using hypertext as the engine of application state (HATEOAS for short). This is rare to see in practice, as it is rather difficult to implement. The cowboy approach is far easier, as the cowboy coder gets to build things in an idiosyncratic way while breaking client implementations and creating busy work.
What hypertext imposes is that links to other resources are embedded in the payload, and in the case of HTML, it’s the humble anchor tag
<a>. It is important to note that links in HTML documents are not necessarily bi-directional, so that it is possible to reach dead-ends everywhere since pages do not necessarily record what links to itself. This sounds redundant to say to anyone who browses the Internet, but in the case of APIs, it is important for a machine client to traverse links from a given state, this promotes self-discoverability.
REST Is Mostly a Buzzword
Too often, an API that operates over HTTP using HTTP semantics is confused for a RESTful API, typically by marketers but also by developers themselves. Instead of building core functionality and writing prose not syntax, API developers and the companies that employ them are overly concerned with short-term goals, rather than longetivity. It’s the move fast and break things motto applied to API design, with sub-par results as expected.