HTTP Verbs Guide & Reference

Understanding HTTP Methods: The Foundation of Web APIs

HTTP methods, also known as HTTP verbs, define the type of action a client wants to perform on a server resource. They are the foundation of RESTful APIs and web communication. While browsers primarily use GET and POST, modern APIs leverage the full spectrum of HTTP methods to create clear, semantic interfaces. Understanding these methods deeply is essential for designing and consuming APIs effectively.

The HTTP specification defines several methods, each with specific semantics that inform how servers should handle requests and how clients should interpret responses. Choosing the correct method is not just about making things work—it enables caching, improves debugging, and communicates intent to other developers.

Safe and Idempotent: Key Concepts

Two properties define HTTP method behavior: safety and idempotence. Understanding these helps you design reliable systems and troubleshoot issues.

A safe method never modifies server state. GET and HEAD are safe—calling them should only retrieve data without side effects. This means browsers can prefetch safe URLs, search engines can crawl them, and caches can serve them freely. Never use GET to trigger actions like deleting data or sending emails.

An idempotent method produces the same result when called multiple times. PUT and DELETE are idempotent: deleting a resource twice leaves it just as deleted as deleting it once. POST is explicitly not idempotent—submitting a form twice might create two orders. This property matters for retry logic: it is safe to retry idempotent requests after network failures without risk of duplicate effects.

GET: The Read Operation

GET requests retrieve data without modification. They should be safe and idempotent—reading the same resource multiple times should always return the same data (assuming no other changes occurred). GET requests should never have side effects like creating records or sending notifications.

GET requests carry parameters in the URL query string, not the body. This makes them bookmarkable and cacheable but limits the amount of data you can pass (URLs have practical length limits around 2000 characters). For complex queries requiring more data, consider POST with a search body, though this sacrifices cacheability.

Responses to GET requests are cacheable by default. Browsers, CDNs, and proxy servers can store and reuse responses, dramatically improving performance. Use cache headers to control this behavior: Cache-Control, ETag, and Last-Modified guide cache behavior.

POST: Creating Resources

POST creates new resources on the server. Unlike PUT, where the client specifies the resource location, POST lets the server decide the URI for the new resource. When you POST to /users, the server creates a user and returns the location (e.g., /users/123) in the response.

POST is neither safe nor idempotent. Each POST request might create a new resource, which is why browsers warn before resubmitting POST forms. The server should respond with 201 Created for successful resource creation, including a Location header pointing to the new resource.

POST is also the catch-all for operations that do not fit other methods. Complex operations, batch processing, or actions that are not strictly CRUD might use POST even when they do not create resources. This flexibility is powerful but can lead to less semantic APIs if overused.

PUT: Full Replacement

PUT replaces a resource entirely with the provided representation. If you PUT to /users/123, you must include the complete user object—every field. Fields not included are typically set to null or default values, not preserved from the existing resource.

PUT is idempotent: putting the same resource multiple times has the same effect as putting it once. This makes PUT safer to retry after network failures. If a PUT request times out, you can safely resend it without worrying about duplicate effects.

An interesting behavior: PUT can create resources if the URL does not exist, provided the client can specify the URI. PUT /articles/my-custom-slug could create an article at that exact location. This differs from POST, where the server assigns the location.

PATCH: Partial Updates

PATCH modifies part of a resource without replacing it entirely. You send only the fields that should change, and the server merges them with the existing resource. This is more efficient than PUT when you only need to update one field of a large resource.

PATCH is technically not guaranteed to be idempotent, though many implementations treat it as such. The RFC specifies that PATCH applies a set of changes, and applying the same changes twice might not always produce the same result (e.g., "increment counter by 1" is not idempotent). In practice, most APIs implement idempotent PATCH behavior.

The format of a PATCH request body varies. JSON Merge Patch (application/merge-patch+json) is simple: just send the fields to update. JSON Patch (application/json-patch+json) is more powerful, supporting operations like add, remove, replace, move, and copy with explicit instructions.

DELETE: Removing Resources

DELETE removes the specified resource from the server. It is idempotent: deleting an already-deleted resource should not cause an error (though the second call might return 404 instead of 200, the state is the same—the resource does not exist).

Soft delete versus hard delete is an implementation decision. Some APIs mark resources as deleted without actually removing data, allowing recovery. Others permanently remove data. The appropriate choice depends on business requirements, regulatory needs, and storage considerations.

DELETE requests typically do not include a body, though the HTTP specification does not prohibit it. Some servers ignore DELETE bodies, so avoid relying on them. If you need to send data with a DELETE (like a reason or confirmation), consider using a custom header or query parameter.

Other HTTP Methods

HEAD is identical to GET but returns only headers, no body. Use it to check if a resource exists or get metadata without downloading the entire content.

OPTIONS describes the communication options for a resource. CORS preflight requests use OPTIONS to check if a cross-origin request is allowed before sending the actual request.

CONNECT establishes a tunnel to the server, typically for HTTPS through an HTTP proxy. TRACE performs a message loop-back test, rarely used in production due to security concerns.

Choosing the Right Method

Follow these guidelines for RESTful design: Use GET for reading, POST for creating (when the server assigns the ID), PUT for replacing (when the client specifies the full resource), PATCH for partial updates, and DELETE for removal.

When the operation does not fit neatly into CRUD, consider the semantics. If the operation is safe and idempotent, GET might work (though be careful with URL length). For actions with side effects, POST is the typical choice. Some teams introduce a /actions sub-resource for non-CRUD operations: POST /orders/123/actions/cancel.

Whatever you choose, be consistent and document your API well. The best API is one that developers can use correctly without reading extensive documentation, and proper method usage is a big part of achieving that goal.