HTTP Methods and why you should be using them on your API
Tags: webdev, beginners
Published: 2019-08-02 11:10:54

Every single one of us has, even if without knowing, used the **HTTP** protocol before. Otherwise, I wouldn’t have written this on DEV Community 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 the 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 **PATCH**ing 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.