RESTful - Understanding the most common HTTP verbs and Return Codes

Hello folks! I want to share with you some knowledge about the most common HTTP verbs and Return Codes and an explanation about each one. I hope you enjoy it.

First of all, when we are talking about RESTful, we are talking about APIs.

But first, what is an API (Application Programming Interface)?

Image Source

I love this image. It helps us to easily understand what is an API right away (at least it is what I hope. lol)

So, basically in this image we can see a client, a waiter and, a chef. In this scenario our API is the waiter.

Why? Because, we don't need to know HOW the food is made, we just need to know how to REQUEST the food.

That's why the APIs are so important when we are trying to communicate between services, with a good documentation (e.g. swagger), we can see how to create the request and how the response will look like.

Ok, after this brief explanation about what is an API, let's move on to the main topic of this post.

RESTFul APIs

Let's start talking about the most commons HTTP verbs used (based on my experience):

• GET
• POST
• PUT
• DELETE

And, in some scenarios:

• PATCH

We often see those verbs in applications that we call - CRUD -> Create, Read, Update and Delete - applications.

So, let's imagine a CRUD of Users. What does it mean?
Our service will be responsible for:

• Save a new user in our database;
• Retrieve one/all the users from our database;
• Update an user information in the database;
• Delete an user information from the database;

And, in some scenarios:

• Partially update an user information in the database;

We have the scenario ready, let's talk about each verb now.

GET

We are going to use this verb every time we want to RETRIEVE some information. In this scenario, we would use the GET to retrieve one or all the users from our database.

POST

We are going to use this verb every time we want to CREATE a new entry. In this scenario, we would use the POST to create a new user in our database.

PUT

We are going to use this verb every time we want to UPDATE an information. In this scenario, we would use the PUT to update a user information in our database.

DELETE

We are going to use this verb every time we want to DELETE an information. In this scenario, we would use the DELETE to delete a user information from our database.

PATCH

We are going to use this verb every time we want to PARTIALLY UPDATE a user information. In this scenario, we would use the PATCH to partially update a user information in our database.

Let's just do a little comparative about POST vs PATCH, just to make the difference clear for you.

PUT vs PATCH

Let's imagine that our User data in the database is composed by:

• name = Gabriel
• age = 25
• city = Campinas

And now, let's see the differences between both requests:

• PUT

{
    "name":"Gabriel",
    "age": 26,
    "city": "Campinas"
}

• PATCH

{
    "age": 26
}

What can we see here?

Both request are doing the exactly same thing, updating the age information from the user.

But, the difference is, when we are using the PUT verb, we must pass the whole object - even if nothing but age will be changed.

Otherwise, if we have a PATCH endpoint configured, we can just pass the field we really want to change - more simple, isn't?

Can I conclude here that our POST request and PUT request will be the same? Yes! You're completely right.

There is some cases where the client tries to update a User, but the User does not exist in the database, so, instead of update the application creates a new User with that information.

Ok, I hope you are understanding a little bit more about the verbs, now let's talk about the Return Codes

Return Codes

There are lots of returns codes, really, you can check all of them here. It goes from 100 until 599. (I meant it when I said a lot)

Basically, what we can know about each range:

100 - 199 -> Informational
200 - 299 -> Success
300 - 399 -> Redirect
400 - 499 -> Client error
500 - 599 -> Server error

But the focus here is to show and explain the most common ones (based on my experience).

So, keeping with our CRUD User scenario, let's go a little deeper and check our endpoints:

• GET /users
• GET /users/{userId}
• POST /users
• PUT /users/{userId}
• PATCH /users/{userId}
• DELETE /users/{userId}

Perfect! We talked about the verbs and, for your surprise, those verbs are linked with the return codes.

Most common Return Codes

• 200 (OK)
• 201 (CREATED)
• 204 (NO CONTENT)
• 400 (BAD REQUEST)
• 401 (UNAUTHORIZED)
• 403 (FORBIDDEN)
• 404 (NOT FOUND)
• 405 (METHOD NOT ALLOWED)
• 422 (UNPROCESSABLE ENTITY)
• 500 (INTERNAL SERVER ERROR)
• 502 (BAD GATEWAY)
• 503 (SERVICE UNAVAILABLE)
• 504 (GATEWAY TIMEOUT)

Yes, that's are my most common return codes, let's see more about them.

200 (OK)

It's pretty straight forward - your request has been executed successfully and you got your response body with all the information.
We often use this return code for GET requests.
There are scenarios where we return 200 for a POST request either - but that's for another post.

201 (CREATED)

When we are creating - POST - a new User into our database, the better return code for this scenario is this one. Without a body response.

204 (NO CONTENT)

We often use this one when we are updating or deleting an information from our database. The client just need to know if his request works good. So, we don't need to retrieve a body response.

400 (BAD REQUEST)

We use this return code when the client tries to make the request incorrectly, due a typo or whatever other reason. We return this error and a response body showing him what he did wrong.

401 (UNAUTHORIZED)

When we have authentication in our application, we have to validate the credentials of the client before he could make the request. So, if the credentials are invalid, then we use this return code.

403 (FORBIDDEN)

That's the next step after the validation of credentials, we will validate if those credentials have permission to access that particularly resource.

So, based on our User scenario, a determined credential could retrieve all the users through the GET /users, but that credential could not DELETE or UPDATE a user, so it will receive a Forbidden if it tries.

404 (NOT FOUND)

We are trying to retrieve just a user information through GET /users/{userId}, but the userId informed is not present in the database, then we return a NOT FOUND for the client.

405 (METHOD NOT ALLOWED)

This one could be some causes, just a space in the end of the URL could cause it, or a wrong HTTP verb.

422 (UNPROCESSABLE ENTITY)

I often use this one when something wrong goes with the business rule.

For example, if we should only add users with 18+ years, and I try to add a younger user, my application should return a 422 with a response explaining the reason of that.

500 (INTERNAL SERVER ERROR)

Pretty straight forward as well - an unexpected error happened in our code, then we use this one.

502 (BAD GATEWAY)

Some architectures, in most cases, make usage of a Gateway - to grant more security and so - and this return code happens when the gateway receives an unexpected response, which it does not know how to process, then it returns this code.

503 (SERVICE UNAVAILABLE)

When the application cannot process your request at that moment, it's not ready.

504 (GATEWAY TIMEOUT)

As mentioned in the 502, we have a gateway between our request processing, but this time the gateway itself takes too long to process and throws a timeout.

Conclusion

I hope it can help you all to understand a little bit more about the HTTP verbs and Return Codes used in the RESTful APIs.

Also, a lot of that information already was asked for me in interviews.

Tell me in the comments if you learned something new or even if you missed a HTTP verb or a Return Code that I didn't mention.

So, I hope it could be useful for your careers.

That's all folks! Hope you guys enjoyed. See you!