It doesn't matter what kind of developer you are, if you write APIs or would like to learn, you should know who Leonard Richardson is and how he can help you.

I’m more of a front-end developer, and just recently started writing APIs, so I had no idea who Richardson was until a while ago. Leonard Richardson is an expert on restful API design who proposed in 2008, a maturity model for REST services. The idea is to grade the services based on how much they comply with the constraints of REST.

He proposed a maturity model consisting of four levels. It goes from level 0, which is the most basic implementation of a service, all the way up to level 3, which means the service is totally REST compliant.

How does it work?

Level 0
Services at this level will use HTTP basically as a tunneling mechanism for remote interactions. They will have a single URI for all interactions and won’t use the correct HTTP verbs, typically using POST for everything.

Level 1 - Resources
At this level the services improve a bit, having separate URIs for different interactions. The use of HTTP verbs (or in this case, the lack of it) remains the same.
Only by separating resources among different URIs the services are already a lot better than those at level 0, but can't be considered RESTFUL yet.

Level 2 - HTTP verbs
This is where the majority of services are. At this level, they use separate URIs for the many resources, and the correct HTTP verbs, not simply spamming POST for everything.

But here we have a little controversy. Some say that reaching this level of maturity is already enough to call this service RESTFUL, while others say that you can only claim that at level 3. Either way, at this level you have much more mature services that are easier to use and understand from the documentation.

Say you are developing endpoints for a company that sells video games. One of the first things you may need is to show a list of available titles. For that, you can make a GET request to an endpoint like this: /api/v1/games. Simple as that.

Now say that a new game was released and you need to add it to the company's catalog. You can use a POST request to /api/v1/games/ and pass the game’s information on the request.

Sales season is coming and you need to update the price? No problem, just do something like this PUT: /api/v1/games/{id}.

Something won’t be sold anymore? Maybe this will help DELETE: /api/v1/games/{id}.

Did you notice that to edit and delete you can basically use the same URI, changing only the HTTP verb? That makes it easier to understand what is going on. Using the correct HTTP verbs allows you to write much cleaner endpoints.

Maybe you’ve seen something like this for a CRUD:
/api/v1/games/listAll
/api/v1/new/game
/api/v1/edit/game/{id}
/api/v1/delete/game/{id}

I don’t know about you, but for me, this kind of naming is more confusing and harder to read.

How to improve it?

By using the first approach you can have shorter URIs and even use the same prefix for the entire controller, having even more concise naming. For example, if you use /api/v1/games for the controller, the other endpoints can look like this:
GET: /
POST: /
PUT: /{id}
DELETE: /{id}

See what I mean? It’s much cleaner, easier to read, easier to maintain and you even write less code.

Level 3 - Hypermedia
The last level introduces the use of hypermedia controls, or HATEOAS (Hypermedia as the engine of application state). The idea here is that the response to a request would hold the information necessary for other operations.

Let’s say you make a GET request for the list of available games. Besides returning what you requested, the response could also return the URI for updating the price and deleting the game, for example. With this, whoever is consuming the API wouldn’t need to know its endpoints beforehand, they would only need to know the entry point, and the rest would be shown on the responses.

Another advantage of this is the liberty it gives to the back end to change and evolve if the front end keeps an eye out for these changes. Remember that all the front end needs to know is the entry point, and subsequent steps would be given in the responses. By doing this the backend can change freely without breaking anyone who’s consuming the API, because they will be looking for the data in the responses, not using predefined routes.

And now?

For me, level 2 should be the primary goal of anyone working with APIs. The benefits massively outweigh the complexity of reaching this level of maturity.

If you want to take your APIs to the next level (literally), the use of hypermedia controls should bring valuable benefits to those building the APIs and those consuming them.