http-methods

Every Verb Is a Promise

HTTP methods are not suggestions. They are a contract between your API and every client, proxy, cache, browser, and crawler that will ever touch it. When you label an endpoint GET, you promise it is safe to retry, safe to cache, and will never modify state. When you use POST, you acknowledge that duplicates are possible without explicit safeguards. Getting this wrong does not just break conventions — it breaks infrastructure assumptions that the entire web stack relies on.

The five core methods — GET, POST, PUT, PATCH, DELETE — cover virtually every API operation. The rules below are drawn from the HTTP/1.1 specification (RFC 7231), Stripe, GitHub, Google, Zalando, and Microsoft REST API guidelines. Where these sources converge, treat the pattern as settled law.

GET — Read Without Side Effects

GET retrieves a resource or collection. It is safe (no side effects), idempotent (same result every call), and cacheable.

Rules:

• Never modify server state in a GET handler. Not "usually" — never. The Google Web Accelerator incident of 2005 pre-fetched links on pages, deleting records on sites that used GET for destructive operations.
• Never include a request body. The HTTP spec allows servers to ignore it, and many proxies strip it entirely.
• Return 200 OK with the resource body, or 404 Not Found if the resource does not exist.
• Support conditional requests with ETag and If-None-Match headers. Return 304 Not Modified when content has not changed — this is free performance.
• Use query parameters for filtering, sorting, and pagination. Never encode filters in the path.

GET /orders                          → 200 OK (collection)
GET /orders/789                      → 200 OK (single resource)
GET /orders?status=pending&sort=-created_at  → 200 OK (filtered, sorted)
GET /orders/789 + If-None-Match: "etag"     → 304 Not Modified

BAD:

GET /orders/789/cancel               → Modifies state via GET
GET /getOrderById?id=789             → Verb in URL, filter as query param for identity