Developers often through around the term “RESTful API”, but we aren’t always on the same page about what “RESTful” means. I enjoyed this Martin Fowler article on the Richardson Maturity Model because of its helpful explanation of the steps toward REST.
As a developer consuming APIs, I can get frustrated with APIs that are on lower rungs of this model. Their resources are not easily identified, and interacting with them can be a headache. When I work with APIs like this, I find myself referring to the API documentation way more than I would like to. Unfortunately, it’s hard to avoid doing so because the API is not necessarily consistent across resources.
My favorite APIs to work with have clearly identified resources and use HTTP verbs as you might expect. Recently, I’ve had the pleasure of working with some APIs that implement hypermedia controls. Fetching a resource, requesting more information about its associated resources, and manipulating resources are easy because the API itself provides clues about where to go next.
If you find yourself designing and writing APIs I sometimes do, please check out Fowler’s article.