HTTP methods: Idempotency and Safety

Idempotency and safety are properties of HTTP methods. The HTTP RFC defines these properties and tells us which HTTP methods are safe and idempotent. Server application should make sure to implement the safe and idempotent semantic correctly as clients might expect it.

Safe HTTP methods

HTTP methods are considered safe if they do not alter the server state. So safe methods can only be used for read-only operations. The HTTP RFC defines the following methods to be safe: GET, HEAD, OPTIONS and TRACE.

In practice it is often not possible to implement safe methods in a way they do not alter any server state.

For example, a GET request might create log or audit messages, update statistic values or trigger a cache refresh on the server.

The RFC tells us here:

Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.

Idempotent HTTP methods

Idempotency means that multiple identical requests will have the same outcome. So it does not matter if a request is sent once or multiple times. The following HTTP methods are idempotent: GET, HEAD, OPTIONS, TRACE, PUT and DELETE. All safe HTTP methods are idempotent but PUT and DELETE are idempotent but not safe.

Note that idempotency does not mean that the server has to respond in the same way on each request.

For example, assume we want to delete a project by an ID using a DELETE request:

DELETE /projects/123 HTTP/1.1

As response we might get an HTTP 200 status code indicating that the project has been deleted successfully. If we send this DELETE request again, we might get an HTTP 404 as response because the project has already been deleted. The second request did not alter the server state so the DELETE operation is idempotent even if we get a different response.

Idempotency is a positive feature of an API because it can make an API more fault-tolerant. Assume there is an issue on the client and requests are send multiple times. As long as idempotent operations are used this will cause no problems on the server side.

HTTP method overview

The following table summarizes which HTTP methods are safe and idempotent:

If you are interested in more REST related articles, have a look at my REST API design page to find more articles.