HTTP Methods: Safe, Idempotent and Cacheable — REST APIs in Depth

RFC 9110 defines method properties clients and intermediaries rely on. Safe methods (GET, HEAD, OPTIONS) must not change state. Idempotent methods (GET, PUT, DELETE, plus safe ones) can be repeated with the same effect — so clients, proxies and SDKs may retry them automatically. POST is neither, so it needs idempotency keys for safe retries. PATCH applies a partial modification: JSON Merge Patch (RFC 7396) for simple updates, JSON Patch (RFC 6902) for operations like array edits.

Method properties (RFC 9110)

Method	Safe	Idempotent	Cacheable	Typical use
GET	Yes	Yes	Yes	Read a resource or collection
HEAD	Yes	Yes	Yes	Metadata only (size, ETag)
POST	No	No*	Rarely	Create in a collection, run an action
PUT	No	Yes	No	Replace / create at a known URI
PATCH	No	Not guaranteed	No	Partial update
DELETE	No	Yes	No	Remove

PATCH /users/42
Content-Type: application/merge-patch+json

{"display_name": "Ada", "phone": null}      // null removes the field

PATCH /users/42
Content-Type: application/json-patch+json

[
  {"op": "replace", "path": "/display_name", "value": "Ada"},
  {"op": "add", "path": "/tags/-", "value": "beta"},
  {"op": "test", "path": "/version", "value": 7}
]

* POST becomes retry-safe when the server honors an Idempotency-Key header.

Common pitfalls

GET endpoints with side effects (crawlers and prefetchers will trigger them).
PUT used for partial updates, wiping omitted fields.
Treating PATCH as idempotent when it applies relative changes (increments, appends).

Key points

Safe ⇒ no state change; idempotent ⇒ retry-safe
POST needs idempotency keys for retries
Merge Patch for simple partial updates, JSON Patch for operations

Further reading: RFC 9110: Method properties

Practice questions

Why is it dangerous for a GET request to change state?

Answer

GETs are assumed safe: browsers prefetch, crawlers follow links, proxies and clients retry them. A state-changing GET can be triggered unintentionally and repeatedly.

When would you choose JSON Patch over JSON Merge Patch?

Answer

When you need operations Merge Patch can't express: editing array elements, moving values, or a test operation for optimistic checks. Merge Patch is simpler for replacing/removing object fields.