HTTP Methods

The HTTP specification includes a collection of methods that are used to interact with server-side resources. There are commonly referred to as HTTP request methods or HTTP verbs and are intended to cover all possible types of interaction with resources.

While HTTP request methods typically perform different operations, there is an overlap in functionality, and depending on the task, several HTTP requests will have to be made before it is complete. There are also HTTP method properties to consider, including whether a HTTP request is safe, idempotent, or cacheable.

Methods

General-purpose servers are required to support the HTTP GET and HEAD methods, whereas all of the other HTTP methods are optional.

GET

The HTTP GET method is called by the client to retrieve the current representation of a specified resource. It is the primary operation for most servers.

HEAD

The HTTP HEAD method is the same as HTTP GET but only transfers the status line and the HTTP response Headers. No message body is included.

OPTIONS

The HTTP OPTIONS method is called by the client to inquire about what operations are available for the specified resource or server in general.

TRACE

The HTTP TRACE method is called by the client to perform a loopback test on the path to the specified resource or one of the proxies in the request chain.

DELETE

The HTTP DELETE method is called by the client to remove the specified resource and all of its current representations from the server.

PUT

The HTTP PUT method is called by the client to replace the specified resource and all of its current representations, if any, on the server. It is also used to create resources.

POST

The HTTP POST method is called by the client to interact directly with the resource.

PATCH

The HTTP PATCH method is similar to HTTP PUT in that it is called by the client to change a resource on the server. However, it intended to replace only parts of it. This method can also be used to create resources.

CONNECT

The HTTP CONNECT method is called by the client to establish a tunnel to the origin server, identified by the request-target.

Method properties

HTTP requests have different properties and there are some important commonalities. Request methods can be safe, idempotent, and/or cacheable.

Safe

A safe HTTP method can be thought of as one that is read-only, concerning what happens on the server. In theory, a HTTP method that is safe will not have any effect on the state of the server. However, in practice, this is often not realistic because there is no guarantee that the server does not generate side effects as a consequence of the HTTP request.

For example, if each HTTP GET request causes a publicly visible “visitor counter” to change, then technically, the state of the server has changed. Importantly, the HTTP GET operation is still considered safe because the client did not request the side effect.

The safe HTTP methods are: GET, HEAD, OPTIONS, and TRACE.

Idempotent

An idempotent method has an identical outcome if called multiple times. This means that after the initial HTTP request is sent, successive HTTP requests are of no consequence.

The idempotent HTTP methods are: GET, HEAD, OPTIONS, TRACE, DELETE, and PUT. Notice that all safe methods are idempotent, but DELETE and PUT are not safe because they intentionally affect the state of the server.

Consider what happens when an HTTP DELETE request is made to remove a file on the server:

Initial request

DELETE /documents/old-news HTTP/1.1
Host: www.example.re

Response to initial request

HTTP/1.1 200 OK

Second request – attempting to delete the same file

DELETE /documents/old-news HTTP/1.1
Host: www.example.re

Response to second request

HTTP/1.1 404 Not Found

Take note that the HTTP response is different because the file had already been removed. However, the subsequent DELETE did not alter the state of the server, which means that multiple calls led to the same outcome. Hence, the DELETE method is idempotent.

Cacheable

A cacheable method generates a HTTP response that can be cached. A cached HTTP response is a server-returned result that can be stored and referenced in the future, circumventing the need to make a subsequent HTTP request for the same resource. This is a bandwidth-conserving technique that prevents the unnecessary fetching of identical data from the server.

HTTP GET and HEAD requests are cacheable, and their HTTP responses may be as well.

Responses to HTTP POST and PATCH requests may also be cacheable. This depends on the options that are set, the HTTP headers, and the freshness of the cached resource.

HTTP requests can also invalidate a cached resource, causing it to become stale. For example, if an HTTP PUT request is sent to the server and there is a locally cached version of the target resource that was retrieved using an HTTP GET, it will be marked as stale because HTTP PUT is not a safe method.

Takeaway

HTTP methods are a basic set of operations that can be used to interact with the server, as identified by a specific target resource. HTTP methods can have varying effects on the state of the server, which depend on whether they are safe and/or idempotent, and not all HTTP methods are supported for all resources.