HTTP Methods Reference
An HTTP method states the requested semantics of an operation. Choose methods by their defined behavior—especially safety and idempotency—rather than treating them as arbitrary route labels.
Safety and idempotency
A safe method is intended for information retrieval and does not ask the server to change application state. GET, HEAD, OPTIONS, and TRACE are defined as safe, although servers still produce incidental logs and metrics. An idempotent method has the same intended effect when the same request is repeated. PUT and DELETE are idempotent even when repeated responses differ. POST and PATCH are not guaranteed idempotent, though an API can add idempotency keys.
| Method | Safe | Idempotent | Typical use |
|---|---|---|---|
| GET | Yes | Yes | Retrieve a resource or collection. |
| HEAD | Yes | Yes | Retrieve response metadata without the representation body. |
| POST | No | No | Create subordinate resources or invoke non-idempotent processing. |
| PUT | No | Yes | Create or replace the state of a known target. |
| PATCH | No | Not guaranteed | Apply a partial modification document. |
| DELETE | No | Yes | Remove the selected resource state. |
| OPTIONS | Yes | Yes | Describe communication options; browsers use it for CORS preflight. |
GET and HEAD
GET retrieves a representation and is the primary method for cacheable API reads. Keep sensitive values out of URLs because paths and queries commonly enter histories, logs, and referrers. Request content on GET has no generally defined semantics and may be rejected by intermediaries. HEAD should return the headers a corresponding GET would return, without the response body, making it useful for metadata and validators.
POST
POST submits content for resource-specific processing. It commonly creates a resource under a collection or initiates an action whose final URI is not chosen by the client. On creation, return 201 and a Location header when applicable. For asynchronous work, 202 can point to operation status. Protect retried creation and payment requests with a documented idempotency-key mechanism.
PUT versus PATCH
PUT commonly asks the server to create or replace the state of the target URI with the supplied representation. Repeating the same PUT should converge on the same state. PATCH carries a partial modification document whose semantics depend on its media type, such as JSON Patch or Merge Patch. A patch that increments a counter is not naturally idempotent; a patch that sets a field can be.
DELETE
DELETE removes the association or state represented by the target. The first request might return 204 while a repeat returns 404, yet the method remains idempotent because the resulting absence is the same. Document whether deletion is immediate, asynchronous, reversible, or a soft delete. Use conditional requests when concurrent updates must not be discarded.
OPTIONS and method discovery
OPTIONS can describe communication choices and is used by browser CORS preflight. A 405 response should include an Allow header listing supported methods for the target. Do not require normal endpoint credentials before handling a valid preflight. Gateways and proxies must forward the intended methods instead of routing API writes to a static host.
Retries and method choice
Idempotency reduces risk but does not make unlimited retries safe. Bound attempts, back off with jitter, and honor deadlines. For non-idempotent writes, use a stable idempotency key or operation status lookup. Never convert a write into GET merely to work around routing or client restrictions.
Frequently Asked Questions
How do safe and idempotent differ?
Safe concerns requested state change; idempotent concerns repeated effect.
Should updates use PUT or PATCH?
Use PUT for replacement and PATCH for a documented partial modification.
Can repeated DELETE return 404?
Yes. Idempotency does not require identical responses.