HTTP Methods and why you should be using them on your API

Every single one of us has, even if without knowing, used the HTTP protocol before. Otherwise, I wouldn’t have written this on Medium and, therefore, you wouldn’t be reading it.

When writing REST API’s one should ensure that it uses the standard HTTP methods. These are a great pillar to build a stable and, very important, scalable API. GET, POST, PUT… which one should I use? My answer to that is: depends on what you want to do!

When should I use each method?

The main HTTP verbs, or methods if you prefer to call them that, are:

• GET
• POST
• PUT / PATCH
• DELETE

You may be like:

“Hey thanks, I didn’t know about that! But… when am I supposed to use each one of them?”

Let me explain them to you (and hopefully don’t make this too boring)!

GET

If you check the specification of the HTTP/1.1 protocol it says, and I quote:

“The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.”.

Simplifying this is to say that the GET verb (or method) should be used to retrieve the information you’re looking for. Take the following URL:

https://api-url.dev/api/v1/users/1

It should retrieve all the accessible information about the user with the ID 1.

POST

Let us check the specification of the HTTP/1.1 protocol yet again. It says:

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions:

- Annotation of existing resources;

- Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;

- Providing a block of data, such as the result of submitting a form, to a data-handling process;

- Extending a database through an append operation.

Well, these are a lot of words to say that the POST verb to store information on the server.

Take the following URL:

https://api-url.dev/api/v1/users

This should be used to create a new user. You can send all the required information (username, password, etc.) using the body of the HTTP request you’re going to make.

PUT / PATCH

Let us check the HTTP/1.1 protocol one more time. What does it say about PUT verb?

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server.

In other words, the text above is telling us that we should use the PUT verb to update an existing resource, say, for instance, an existing user.

Using the URL:

https://api-url.dev/api/v1/users/1

The system should update the information regarding user with the ID 1 with the information sent in the request.

But… what about the PATCH verb?

Right! The PATCH verb. Say, for instance, that you want to update the user with the ID 1, like the example right above, but you just want to send just the newly updated field, let’s say the password field. In this case, you should use the PATCH verb. Why? Because you’re just sending a fragment of the user entity, which in this example is the password, thus this verb is adequate as you’re PATCHing the given user.

DELETE

Ah, the last but not the least: the DELETE verb. So, checking the specification one last time (finally no?) we get the following:

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

Deciphering the slightly confusing text it says that you should be using the DELETE verb every time that you want to remove some resource from the server.

If you execute a DELETE request on the following:

https://api-url.dev/api/v1/users/1

The server should delete the user with the ID 1 and, perhaps, all the resources associated with him.

And that’s it! I’ve covered up everything I’ve proposed at the beginning of the article. Hope that you enjoyed the reading and let me know if you have any question or suggestion to improve.

Cheers,