DEV Community

Cover image for About well designed REST APIs
Igor Duca
Igor Duca

Posted on

About well designed REST APIs

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.

wrong endpoint design

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.

correct endpoint design

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:

list of crud actions with correct endpoint designs

  • 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)

Collapse
 
webjose profile image
José Pablo Ramírez Vargas

POST is to create only. PATCH is for UPDATE. PUT is for UPDATE or UPSERT.

Collapse
 
yelldutz profile image
Igor Duca

thanks!

Collapse
 
silvairsoares profile image
Silvair L. Soares

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.

Collapse
 
yelldutz profile image
Igor Duca

Strongly agree!