Part 2 - What you need to know about methods and status codes from the HTTP Protocol
On my last article, I showed you an API RESTful anatomy, that is, the main concepts and terms needed to understand how an API works.
Now, it’s time to go a little deeper, so here I’ll show more about the HTTP protocol, its methods and status codes.
Before we go on, let’s start by clarifying what they do and what their role is.
HTTP means HyperText Transfer Protocol, and it is the standard data communication protocol for the internet. In other words, HTTP defines and makes the communication between web browsers and web servers easier.
When we talk about methods, they basically refer to actions allowed within an API. And about status codes, they are the default responses from an API. Both of them are part of the HTTP protocol definitions.
All set, now we can go deeper on these methods and status codes used on this protocol.
Methods
We’ll talk about 5 main methods. Probably, they will be present in 99% of your time as a developer.
The GET Method
This will be the most used method of all, because it’s used to search data in APIs.
Its main idea is pretty simple. Use a Query String structure to send your query parameters and, when successful, the server will return that data. If you don’t send the query string on your URL, the API will respond with all data, unfiltered.
If you don’t know what a Query String is, take a step back and read my last article, an API’s anatomy.
Let’s follow the same example, of an API that brings data about gastronomy. Its base URL is:
As a developer, I want data that contains information about white wines that cost less than $100.
To make that request, I’ll use GET:
https://api.mygastronomy.com/wines?max_price=100&type=white
Remember that this API would need to provide query strings parameters (max_price and type) in its documentation so we can use them when making the request.
Or, let’s imagine that I already have the wines list, retrieved on my last request, but I want to check a specific wine, which has the ID number 22.
In this case, I’d make the following request, in which 22 is the {id} parameter on this URL — GET
https://api.mygastronomy.com/wines/22
In this case, we won’t use a Query String, but a URL parameter, because {id} is mandatory.
The POST Method
Now, let’s imagine that you didn’t find a wine that pleases you, and you want to add one on this API. In this case, you would need the POST method to send this new wine data on the request’s body, for instance:
POST https://api.mygastronomy.com/wines with body:
{“name”: “Maycas Reserva Sumaq Chardonnay 2016”,“price”: 49,“country”: “Chile”,“recommended”:”fish, seafood”,“type”: “white”}
Done. You’ve just added a new wine.
PUT e PATCH Methods
The PUT method is used when creating and updating data. If, for instance, I sent that new wine and it already existed there, it would be just updated. If not, a new wine would be created there.
Note: That’s a protocol’s recommendation, so its implementation depends on the developer.
The PATCH method is used to partially update a register. Let’s imagine that the newly registered wine generated the identifier 55, and now I’d like to update only its price. The request would look like this:
PATCH https://api.mygastronomy.com/wines/55 with the following body:
{“price”: 49}The DELETE method
With a self explanatory name, this method is responsible for deleting registers. Therefore, suppose you want to delete that same wine that you’ve just updated. The request would be:
DELETE https://api.mygastronomy.com/wines/55
Other Methods
There are other methods, such as OPTIONS, HEAD and TRACE, but they are rarely used. If you want to, you can check the full list here.
Status Codes
Now, let’s talk about status codes allowed by HTTP, and that can be grouped by their type. These codes are returned by the server, and their function is informing developers what happened after their requests were made.
Group 1
This status group provides informative responses. There are a few of them and they are rarely used.
Group 2
This group refers to the success cases. The most used ones are:
200 OK — The most used one. It indicates that the request was successfully processed.
201 Created — This one indicates that the request was successful and that a new register was created. This response is used when using the POST method to make requests.
Group 3
It defines redirect responses. They are used to inform clients about request changes and the redirecting to another URL. The most common are:
301 Moved Permanently — It informs that resource A is now resource B, so that when a client requests resource A, it will be automatically redirected to resource B.
304 Not Modified — Cache scenarios response. It informs the client that the response was not modified, and in this case, the client can use the same cached version of that response.
307 Temporary redirect — This one is about redirecting a page to another address. It’s a temporary, not permanent change, though.
Group 4
Here’s what you should pay more attention to, because this group informs client-side errors. In other words, if you incorrectly build your request, the server will return an error from this group. Here’s the most important ones:
400 Bad Request — This means that the server couldn’t understand your request, because of some wrong syntax or structure.
401 Unauthorized — This informs that there is a security layer on the requested resource, and that you’re not using your access credentials on that request. Remember that credentials can be a user and a password, a token, etc. It depends on the API you’re consuming.
403 Forbidden — On this, the credentials were recognized, but the server is informing you that the client does not have the access rights to that resource.
404 Not Found — This is when the server does not find the requested resource.
429 Too Many Requests — Not very common, it is used to inform the client that the allowed requests limit has been reached.
Group 5
As important as group 4, this is where the server-side errors are. In other words, you can think that in this case, the client-side request was done correctly, but some processing error has happened on the server side. Let’s check what are the main ones:
500 Internal Server Error — the most generic and used error from this group. It informs you that the server has faced an unexpected error scenario, and it wasn’t able to handle it. Because of that, it wasn’t able to return a response for the client’s request.
503 Service Unavailable — This is generally used to inform that the server is offline, under maintenance or overloaded.
There are many more status codes available for use on the HTTP protocol, but, certainly, I’ve talked about the most used ones.
If you want to check the whole list, check this link.
That’s it, hacker friends! We’ve come to an end of another APIs articles.
Did you like it? Share it and help it impact more developers that may enjoy and find this content useful.
And stay tuned because, soon, the third article will be available. On that, I’ll talk about Authentication and Authorization in RESTful APIs.
See ya!
