Everybody writes REST APIs today.
Everybody knows REST APIs are more generic, scalable and extensible than SOAP and RPC. Or do they?
Like many I started writing REST APIs the Rails way
because Rails provides everything you need to quickly write a beautiful REST API out of the box.
Or so I thought.
After reading many articles and many more comments,
I now understand that most so-called REST APIs today are not actually RESTful according to how REST was originally defined.
Many proponents of “true REST APIs” now seem to prefer talking about Hypermedia APIs which is a more practical description of what they are.
You’ll also hear about the HATEOAS principle, meaning Hypermedia As The Engine Of Application State, one of the constraints of the REST architectural style.
Now I don’t have a doctorate in computer science;
I’m just a lowly software engineer trying to code some APIs.
A big part of software engineering is making trade-offs.
But you have to understand what you’re trading off.
For the rest of this post, I’m going to put on my “True REST & Hypermedia API” zealot hat.
Aside from point 1 which is a summary of what some people incorrectly understand REST to be,
this post reflects my (condensed) understanding of what REST/Hypermedia principles are.
I also describe useful standards and practices that can help to put these principles into practice in an HTTP API.
Note that many people disagree that this is how it should be done.
If you’re interested in knowing more, I’ve listed the articles I found most useful to understand the subject at the bottom of this post.
The comments sections of these articles are particularly interesting as they contain descriptions of actual problems, possible solutions, and mostly thoughtful criticism.
A fair warning to those who may read on: this is a tl;dr kind of post.