We all have struggled at least once with a poorly designed API and I am pretty sure that it is really hard to forget how frustrating it was as a partner that wanted just to integrate it or even just a developer that had to maintain that living hell.
Basics
APIs were created to make easier for other developers to consume and use online content from its direct source. So, the motivation of its creation directly implies on our major concern -- or the thing that we must be concerned at most -- when developing an API: developer-friendly processes.
Endpoints
I have seen all sorts of really messy endpoints, but let us use this article to talk about the good ones.
Good practices while establishing endpoints
I am using express (node.js) to exemplify my point on this section.
You may be used to see endpoints like this one above. They look OK, since its composition exposes its purpose: a /all endpoint should return all of the objects from that collection, right?
Yes, but it will create a much more verbose API while it is scaling. I am not saying it does not work, and it would make no sense if it does not, but, you really don't need to add those suffixes.
The approach below delivers the same result, and at the same time, it makes your endpoints more succinct so their requisitions will be of a easier understanding.
About the requisition methods
The more usual mistakes while choosing the correct requisition method:
- POST for delete ❌
- GET to perform create actions ❌
- PATCH for create actions ❌
Now that you know what not to do, there is an example of how things should look like:
- GET is used to return a list or an unique record ✅
- POST is used to create (insert or upsert) a record ✅
- PATCH is used to update a record ✅
- DELETE is used to delete a record ✅
- PUT is used to upsert a record ✅
Observation: while performing massive actions, those methods will serve at the same way, the only difference will be on their payloads.
Final considerations
It is really important for a developer to understand how his APIs and endpoints should be designed in order to make it easier for other developers for have a good use of his own work.
Choosing the right endpoint names, methods, authorizations, contracts, authentications is a real concern and it should be the way to create a really good or a real bad API.
Photo by Wilhelm Gunkel on Unsplash
Top comments (4)
POST is to create only. PATCH is for UPDATE. PUT is for UPDATE or UPSERT.
thanks!
Just study and implement the RESTFul standard. You don't need to invent anything, nor make your customers have to guess the behavior of your API.
Strongly agree!