Methods

All methods with their properties

Safe means read-only, no intended side effect. Idempotent means N identical requests have the same effect as one. Cacheable means a response may be stored and reused.

Every safe method is idempotent. The reverse is false: PUT and DELETE change state yet are idempotent, which is exactly why clients may retry them after a timeout and may not retry POST.

PATCH is not idempotent in general, because a patch like "increment by 1" depends on the current state. A full replacement patch can be.

GET vs POST

Never put a secret, token, or password in a query string. It lands in access logs, browser history, and the Referer header of the next request.

PUT vs POST vs PATCH

# POST: create, the server assigns the URL
curl -X POST https://api.example.com/orders \
  -H 'content-type: application/json' \
  -d '{"sku":"HU-100","qty":2}'
# → 201 Created, Location: /orders/8814

# PUT: create or replace at a URL the CLIENT chooses, full representation
curl -X PUT https://api.example.com/orders/8814 \
  -H 'content-type: application/json' \
  -d '{"sku":"HU-100","qty":5,"status":"open"}'
# → 200 or 204, omitted fields are cleared

# PATCH: partial update
curl -X PATCH https://api.example.com/orders/8814 \
  -H 'content-type: application/merge-patch+json' \
  -d '{"qty":5}'
# → 200 or 204, untouched fields keep their values

Two standard patch formats: JSON Merge Patch (application/merge-patch+json, RFC 7396) where null deletes a key, and JSON Patch (application/json-patch+json, RFC 6902) which is an array of add, remove, replace, move, copy, test operations.

[
  { "op": "replace", "path": "/qty", "value": 5 },
  { "op": "remove", "path": "/coupon" },
  { "op": "test", "path": "/status", "value": "draft" }
]

HEAD, OPTIONS, and TRACE

curl -sI https://example.com/big.zip        # size and type without the download
curl -sX OPTIONS -i https://api.example.com/orders
curl -s -o /dev/null -w '%{size_download}\n' -I https://example.com

- HEAD must return exactly the headers GET would, including Content-Length, with no body. Use it for existence checks, size probes, and cache validation. A server that computes different headers for HEAD is buggy. - OPTIONS reports capabilities. The response carries Allow: GET, POST, OPTIONS for a resource, and in CORS it is the preflight request carrying Access-Control-Allow-*. - TRACE echoes the received request, which historically enabled Cross-Site Tracing to read HttpOnly cookies. Disable it in production. - CONNECT asks a proxy to open a raw TCP tunnel, which is how HTTPS traverses a forward proxy.

Method restrictions clients actually hit

Choosing status codes per method

405 must include an Allow header listing the methods the resource does support. Omitting it is one of the most common API bugs.