From an architectural point of view REST is simple. And unfortunately, this makes developers actually do the mistake of thinking that it is very easy to design simple things. In reality, the effort and resources required to design and build something is inversely proportional to the simplicity of the end result.
That`s why long-term thinking and the ability to oversee the potential flows in your design is very important not to be limited only to the current release or version of the API.
How to build a REST API
REST is an architectural style intended to be used for long term solutions that can evolve more quickly and efficiently. Even though there are many patterns to guide you during the design and build, is really not so difficult to get it wrong.
As a baseline for designing a REST API, I would advise everyone to use the RMM (Leonard Richardson Maturity Model).
It consists of 4 levels based on which an API can be considered mature.
- Level 0: Define one URI, and all operations are POST requests to this URI.
- Level 1: Create separate URIs for individual resources.
- Level 2: Use HTTP methods to define operations on resources.
- Level 3: Use hypermedia (HATEOAS).
I won`t stop too much on level 0 as this is a basic design approach which doesn’t classify an API as being REST. It definitely needs avoiding during any stages of the software development lifecycle.
Going closer to the REST concept, the RMM is all about resources. You need to identify what resources you have and design the API around them. Avoid having one endpoint doing everything, handling a lot of the complexity based only on what and how many parameters you are sending. You should always break a large service endpoint down into multiple resources that can be consumed more efficiently.
DON`T
POST /getCompanyInfo?Id=23&&nrOfemployees=true&public=false&branches=true&asList=true
Also, continuing with the above example , isn`t confusing that we make a POST request to return the info about the company ? Why this is not a GET request since all you do is just to gather some data from whatever data store you have in the back-end?
Do
GET /companies/23
Use the HTTP request method according to the action performed and don`t use POST for every endpoint you have.
This is another reason why the standard is to use nouns instead of verbs in endpoint paths, as the action should be indicated by the HTTP request method that we’re making in order to remove unnecessary variations.
- GET retrieves resources.
- POST submits new data to the server.
- PUT updates existing data
- etc
Diving even deeper into the daily mistakes we do, how often did you build or work on an existing API with POST endpoints which return the HTTP code of 200(OK) and at the same time in the body of the response it includes the error message explaining that something actually went wrong and the request couldn`t be performed ?
Isn`t it confusing ?
Therefore, the RMM model stresses out the importance of using the HTTP verbs and HTTP response codes during the design of our APIs to indicate the most appropriate and explicit message to the client using it.
- 400 Bad Request – The client-side input fails validation.
- 401 Unauthorized – The user is not authorized to access a resource.
- 403 Forbidden – The user is authenticated but is not allowed to access a resource.
- Etc.
Another very common mistake is to include in the response every possible bit of information so you can be able to make just a single request.
Here the hypermedia controls come into play (or HATEOS– Hypertext As The Engine Of Application State). Instead of returning all of the info you have in one go, return only the resources related to that endpoint and all the linked resources will be identified through the URI which will guide us to the next request we need to do – of course only if we need that info and when we need it.
{
“contact”:”Jane Smith”,
“mobile”:”07568373″,
“address”:” https://api.estate.com/property?id=23“,
…
}
If the above response was meant to return the info about a client then it makes sense not to return in the same response all the info about the property they own. This is where we use the URLs to show you what info is available and how to get it and you won’t need special code to figure out what the links mean – because the Resources must describe their own capabilities and interconnections.
Of course, there are also other things to take into consideration during the design of the REST API; versioning, security, performance, etc. But before you even start to think to invest resources into those areas, make sure at least you have a true and mature REST API which can later evolve more efficiently.
HTTP codes are for transport, not the messages themselves.
Thus this is getting all wrong. Change the transport and you’re stuck in refactoring to “other transport success/error codes”. Think of request/response and it will get simpler and clear, no matter what transport is it.
Yes, REST is independent of any underlying protocol and is not necessarily tied to HTTP. However, most common REST API implementations use HTTP as the application protocol, this is why the RMM (Leonard Richardson Maturity Model) is what I would recommend when designing a REST API.
Therefore we use HTTP methods because we want to define operations on resources and give a semantic meaning to a request.
If you are getting to a point when you need to change your architecture and you are stuck in refactoring because you defined the operations in terms of HHTP methods, then maybe using the REST architectural approach was not the correct solution for your project.
Other options available you may want to try would be GraphQL, gRPC etc.