A URL identifies what a client wants to interact with. The HTTP method expresses the intended interaction. Retrieving a reading list, replacing its settings, and deleting it can use the same URL while making different requests of the server.

Method semantics are those shared meanings.

This chapter explains the intent of the standard methods, how that intent shapes a request, and which details remain the API's responsibility.

An HTTP method is part of the contract visible to clients, servers, and intermediaries. Its meaning does not come only from the application handler's name or the database statement it executes.

For example, the bookstore can support several operations at /reading-lists/list_731. The method distinguishes the requested behavior:

Each arrow describes an interface promise. The server might need multiple database operations to fulfill one request, or no database at all. HTTP methods do not map directly to individual SQL commands.

The main method meanings are:

The examples use https://api.bookstore.example and HTTP/1.1 message syntax. The method meanings also apply to HTTP/2 and HTTP/3. Reading-list operations require a valid caller identity and the appropriate permission; EXAMPLE_TOKEN is a nonfunctional credential placeholder. Each JSON body occupies one line without a trailing newline.

GET requests a representation, data describing a resource in a particular format. For the bookstore's reading list, the representation is a JSON object containing its identifier and settings.

Assume the list exists and the caller owns it:

The service returns:

The client asked to read the list, not change its settings. The server can still record access logs and metrics while handling that read. Such incidental activity does not turn retrieval into a request to modify the list.

A flawed design would use GET /reading-lists/list_731?delete=true to delete it. The query parameter cannot redefine GET as a destructive operation. Browsers and other clients can follow or prefetch links expecting retrieval. The deletion belongs behind an appropriate state-changing method, such as DELETE on the list itself.

Avoid request bodies on GET in ordinary interoperable APIs. They have no generally defined semantics, and clients or intermediaries may reject them. Put a simple retrieval filter in the query string rather than assuming every participant will interpret a GET body.

HEAD requests the metadata a corresponding GET would provide, without response content:

If the server selects the same representation and it remains unchanged, a response can be:

There are no body bytes after these headers. When Content-Length appears in a HEAD response, it describes the body length the corresponding GET would have returned. A server may omit fields whose values it determines only while generating content, so HEAD is not a promise of an identical header set.

HEAD can help inspect a large download's metadata without transferring the file. It does not guarantee cheap server processing, bypass access checks, or reserve the resource against subsequent changes.

POST asks the target resource to process the submitted content according to that resource's rules. Creating a resource is a common use, but it is not POST's only meaning. A calculation, a submission for processing, or a business operation can also fit this intent.

Consider how the bookstore creates the example reading list. The client sends its initial settings to the collection URL, https://api.bookstore.example/reading-lists:

The server chooses the new identifier and returns:

Here, the request target is the collection, while Location identifies the created list. Choosing the identifier on the server is this API's creation convention.

The status depends on what happened, not merely on the method. A POST that completes a calculation can return 200 OK with a result. A POST that the server accepts for later processing can return 202 Accepted. The client needs the documented operation and response to understand completion; POST alone does not mean “create a database row” or “run in the background.”

PUT expresses the desired state of the resource at the request target. If the API permits creation there, PUT can create it; otherwise it replaces the existing state that resource represents.

For this example, assume reading-list PUT requests operate only on existing lists. The complete editable representation has three required fields: name, visibility, and description. The server-managed identifier is not an editable field, and the API manages list membership separately.

The owner replaces the settings at https://api.bookstore.example/reading-lists/list_731:

After replacing those settings, the server returns:

The name changes, visibility remains private because the request explicitly sets it, and the empty string clears the description. In this contract, omitting description is a validation error. It does not mean “keep the old description.”

HTTP does not define the fields in the representation or require clients to submit internal database columns. The API must explain which state PUT replaces and how its schema treats omitted fields. Avoid silently treating a small PUT body as a generic partial update.

If another API permits PUT creation at a client-selected URL, successful creation requires 201 Created. Successful replacement uses 200 OK or 204 No Content. Supporting PUT does not require every API to allow clients to invent new identifiers.

PATCH carries a patch document, content describing changes to apply to the target. The patch format determines how to interpret those changes. The method alone does not establish rules for omitted fields, arrays, or null values.

Assume the bookstore supports JSON Merge Patch for reading-list settings. This format uses application/merge-patch+json. For an object, supplied members modify the corresponding values, while omitted members remain unchanged. A null member requests removal, subject to the resource's validation rules.

After the PUT replacement, the owner makes the list public:

The service applies the change and returns the updated representation:

The name and description retain their current values. application/json alone would identify JSON syntax without identifying these merge-patch rules.

The diagram contrasts the two update intents using this API's settings representation:

The distinction is the requested effect, not merely the size of the request body. A replacement can be small, and a patch can describe many changes.

PATCH requires the server to apply a patch document atomically: either it applies every change or it applies none. If a patch requests a valid name change and an invalid visibility value, the server must not leave the name changed after rejecting the patch. Atomic application does not, by itself, prevent an update based on stale client data from overwriting a newer value.

DELETE asks the server to remove the association between a target URI and its current functionality. For an API consumer, this commonly means the resource is no longer available through its ordinary endpoint. It does not promise physical erasure of every stored copy.

To remove the reading list, the owner sends:

Once removal completes, this service returns:

In this example, subsequent retrieval returns 404 Not Found, and deleting an already absent list also returns 404. Those are this API's documented choices. Another API could treat an already absent resource as a successful no-op. Clients should not infer repeat-request behavior from the first response alone.

The bookstore may retain an audit record internally. It must separately define whether deletion removes list membership, retains history, or starts delayed cleanup. If the service accepts deletion but has not carried it out, it can return 202 Accepted. Once deletion finishes, it can return 200 OK with a result or 204 No Content without one.

As with GET, DELETE request content has no generally defined semantics. This example needs only the target URI and caller credentials. Do not assume a body containing extra deletion instructions will work across arbitrary clients and intermediaries.

OPTIONS requests information about communication options for a target. Consider the list while it still exists:

The bookstore can advertise its supported methods and patch format:

Allow describes the target's supported methods. Accept-Patch advertises supported patch document media types. Neither is a complete operation schema, and neither grants permission to change the list.

Browsers also use OPTIONS for some CORS preflight checks, which ask whether the server permits a cross-origin request. That is one use of OPTIONS, not its entire meaning. Allow is distinct from the CORS-specific Access-Control-Allow-Methods header. An ordinary OPTIONS response does not automatically authorize a browser's cross-origin request.

A method can be valid HTTP even when a particular target does not support it. This bookstore accepts POST on /reading-lists to create a list, but not on /reading-lists/list_731.

Suppose an authorized owner mistakenly sends the creation request to that existing list's URL. The service returns:

A 405 response must include Allow with the target's currently supported methods. Use 501 Not Implemented when the server does not recognize or implement the method. Use 405 when the server recognizes the method but the target does not support it. Rejection of a supported operation because the caller lacks permission is an authorization problem, not a method-support problem.

For a known list visible to an authenticated caller, the bookstore distinguishes these outcomes:

These are different rejection causes. The diagram groups them conceptually rather than prescribing a universal validation order:

Changing the method does not solve a missing permission or an invalid value. The API should communicate the actual problem, while applying its policy for whether it may reveal that the resource exists.

CONNECT asks a server, commonly a forward proxy, to establish a tunnel to a destination. In ordinary HTTP/1.1 CONNECT usage, the target is a host and port, such as api.bookstore.example:443. After a successful response, the connection carries tunnel traffic. This supports communication through a proxy; it is not a method for creating a bookstore resource.

TRACE provides a diagnostic loopback: the final recipient reflects the received request so the client can inspect what arrived. Clients must not send sensitive credentials or cookies in a TRACE request because reflection could disclose them.

Neither method belongs in the reading-list API's application operations. Recognizing their purpose is useful when inspecting network traffic, but supporting an HTTP API does not mean exposing every defined method on every URL.

HTTP methods express intent independently of the server's implementation. GET and HEAD retrieve information, POST requests resource-specific processing, PUT supplies replacement state, PATCH describes changes, and DELETE requests removal. OPTIONS reports capabilities, while CONNECT and TRACE serve tunneling and diagnostic roles.

The method establishes shared expectations; the API contract supplies resource-specific fields, permissions, validation, and completion behavior. Choose and implement methods consistently with both layers so callers can understand what a request asks the service to do.