What does safe mean for an HTTP method?

A safe method is read-only by contract — it must not change server state. GET, HEAD, OPTIONS and TRACE are safe. Safety lets caches, crawlers and prefetchers issue the request freely without side effects.

What is idempotency and why does it matter?

An idempotent method produces the same server state whether it is called once or many times. GET, PUT and DELETE are idempotent; POST and PATCH generally are not. Idempotency lets clients and proxies safely retry a request after a timeout.

Is PUT or PATCH idempotent?

PUT is idempotent because it replaces the resource with the same representation every time. PATCH is not required to be idempotent because it applies a partial change that can compound, though a PATCH can be designed to be idempotent.

Which methods are cacheable?

GET and HEAD are cacheable by default. POST responses are cacheable only when they include explicit freshness headers like Cache-Control or Expires. PUT, DELETE, PATCH, OPTIONS, TRACE and CONNECT are not cacheable.

Why is POST not idempotent?

POST typically creates a new resource or triggers a non-repeatable action, so sending it twice can create two records or run an action twice. Use an idempotency key header if you need safe retries on a POST endpoint.

What is the HTTP Method Properties Matrix?

Reference matrix for HTTP method semantics — safe, idempotent, cacheable, request body and success body — across GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE and CONNECT, with a searchable lookup. It runs free in your browser on Gera Tools, with nothing uploaded.

HTTP Method Properties Matrix

Name: HTTP Method Properties Matrix
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Know each verb’s contract before you wire it up

Every HTTP method carries a semantic contract: whether it is safe (read-only), idempotent (repeatable without extra effect), cacheable, and whether it has a request body. Getting these right decides whether clients may retry, whether proxies may prefetch, and whether responses can be cached. This matrix lists all standard methods with each property and a searchable lookup.

Properties matrix

Method	Safe	Idempotent	Cacheable	Request body	Typical use
GET	Yes	Yes	Yes	No	Fetch a resource
HEAD	Yes	Yes	Yes	No	Check headers without body
OPTIONS	Yes	Yes	No	No	CORS preflight; list allowed methods
TRACE	Yes	Yes	No	No	Loop-back diagnostic (usually disabled)
PUT	No	Yes	No	Yes	Replace a resource entirely
DELETE	No	Yes	No	No	Remove a resource
POST	No	No	Conditionally	Yes	Create, submit, trigger actions
PATCH	No	No	No	Yes	Partial update
CONNECT	No	No	No	No	Establish a tunnel (used for HTTPS proxies)

How it works

The properties are defined by the HTTP specification, not by your framework:

Safe means the method must not modify resources. Safe implies idempotent.
Idempotent means N identical requests leave the server in the same state as one. Useful for retries after network timeouts.
Cacheable means the response may be stored and reused per Cache-Control directives.

A retry after a network timeout is safe only for idempotent methods; for non-idempotent methods like POST, use an Idempotency-Key so the server can de-duplicate.

PUT vs PATCH

PUT replaces the whole resource. If you send a PUT to /users/42 with only a name field, every other field on the user gets removed or reset. PATCH applies a partial change — you only send the fields you want to update.

For example, updating just a user’s email:

PATCH /users/42 HTTP/1.1
Content-Type: application/json

{"email": "[email protected]"}

A PUT to the same endpoint would require sending the complete user object, or accept losing the other fields. PATCH is not guaranteed to be idempotent by the spec — a PATCH that increments a counter is not idempotent — but most field-update patches are designed to be.

Making POST idempotent

POST is not idempotent: submitting a form twice can create two records. To make a POST endpoint safe to retry, accept an Idempotency-Key request header (a client-generated UUID) and de-duplicate on the server:

POST /orders HTTP/1.1
Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479

Store the key alongside the result for a reasonable window (for example, 24 hours). If you see the same key again, return the cached response without re-executing the action. This pattern is used by payment APIs like Stripe.

Tips

All safe methods are idempotent, but not all idempotent methods are safe.
OPTIONS powers CORS preflight; browsers send it automatically before cross-origin requests with custom headers.
HEAD is identical to GET but returns no body — useful for checking if a resource exists or reading metadata before a large download.
TRACE and CONNECT are rarely used and often disabled by security policy.
Cacheability of POST requires explicit Cache-Control or Expires headers in the response, plus a Content-Location header.