Method Verbs

GET, POST, PUT, PATCH, DELETE, these are the most commonly used HTTP verbs.

We will first take a look at the idea of safety and idempotency and then move on to some of the guidelines on when to use each verb and certain things to avoid.

Understanding Safety and Idempotency

Some methods (for example, HEAD, GET, OPTIONS and TRACE) are defined as safe, which means they are intended only for information retrieval and should not change the state of the server. In other words, they should not have side effects, beyond relatively harmless effects such as logging, caching, the serving of banner advertisements or incrementing a web counter. Making arbitrary GET requests without regard to the context of the application's state should therefore be considered safe.

-MDN

The first important definition we need to introduce is what's called a safe operation. A safe operation is one that doesn't modify the resource on the server side. Only the GET method is considered a safe operation, there are other less commonly used methods such as HEAD and TRACE which are also considered to be safe.

In computer science, the term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times. This may have a different meaning depending on the context in which it is applied. In the case of methods or subroutine calls with side effects, for instance, it means that the modified state remains the same after the first call.

-Wikipedia__

The second important definition is the idempotent operation. An operation is considered to be idempotent when it can be applied multiple times without changing the result. All safe operations are idempotent, but not all idempotent methods are safe. The most confusing ones to understand are PUT and DELETE.

In order to understand PUT, let's take an example.

Imagine we had an API endpoint PUT https://example.com/api/users/{user-id} whereby we send in the following request body.

{
  "first_name": "John",
  "last_name": "Doe",
  "height": "1.8m"
}

Do note that the user entity for the response is the same.

if we were to hit that endpoint and pass in that request and update the entity, we would get the same result back. Do it a second, third, fourth, fifth time, and we would still get back the exact same response. This is the reason why the PUT method is idempotent.

For DELETE, it's a little bit trickier to understand. if we were to hit the endpoint DELETE https://example.com/api/users/{user-id} the first time and we delete the entity, we might get a response like the following with a 200 status code.

{
  "message": "User with {user-id} has been deleted"
}

But the second time, we could potentially get a 404.

{
  "message": "User with {user-id} is not found"
}

What's going on here? Does this mean DELETE is not idempotent?

Not necessarily. Idempotence means that making one request has the same end-result as making the same request multiple times, the end-result we are interested in is not the HTTP response or status code. The end-result is the server's state.

Safety and idempotency chart for GET, POST, PUT, PATCH, DELETE.

GET Guidelines

• Only use GET for fetching a singular resource or a collection of resources.

• Do not try to pass data (especially sensitive ones) along the URI of GET requests, use a POST or PUT instead.

• GET must be both safe and idempotent, do not make anything that would lead to a side effect on the server.

POST Guidelines

• Only use POST for creating a new singular resource, nothing else.

• Remember that POST is neither safe nor idempotent, specify if new duplicate resources are created when possible.

PUT Guidelines

• Use PUT to replace an existing resource or a collection of resources.

• Use PUT in favor of POST for resource creation if you know what you want the newly created resource identifier to be.

• Remember that PUT is idempotent, so there should not be any server-related side effects.

PATCH Guidelines

• Use PATCH when updating only a property of a resource. Unlike PUT where a complete representation is specified in the HTTP's request body, PATCH implements a partial update.

DELETE Guidelines

• Only use DELETE for deleting a single resource or a collection of resources.

• Remember that DELETE is idempotent, so there should not be any server-related side effects.

A summary of the GET, POST, PUT, PATCH, DELETE verbs.