APIs & Protocols

GET reads a resource: safe, cacheable, no body. POST creates or triggers an action and is not idempotent — repeating it creates duplicates. PUT fully replaces a resource and is idempotent. PATCH applies a partial update to some fields.

A RESTful application models data as resources addressed by URLs and driven by standard HTTP verbs. Stateless means the server keeps no session between calls — each request carries its own context, so the client resends it every time and any node can serve it.

Safe methods don't change server state — GET, HEAD, OPTIONS. Idempotent methods leave the same end state on repeat — GET, PUT, DELETE. DELETE is idempotent — deleting twice leaves it gone, though the second call may return 404. POST is neither, so repeating it creates duplicates.

200 OK — success with a body. 201 Created — a new resource exists, URL in Location. 202 Accepted — queued for async work, not done yet. 204 No Content — success, no body. 401 means not authenticated (log in); 403 means authenticated but lacking permission.

All three go in the query string of the collection, not the path. Filter by field values — ?status=paid. Sort with a parameter — ?sort=-createdAt (minus for descending). Select fields to trim payload — ?fields=id,total. They compose on one GET /orders, keeping it cacheable.

An HTTP request has a request line (method + URL), headers, and an optional body. A response has a status line, headers, and an optional body. Codes fall into five classes: 1xx informational, 2xx success, 3xx redirection, 4xx client errors, 5xx server errors.

OpenAPI (formerly Swagger) is a machine-readable, language-agnostic description of a REST API in YAML or JSON. It lists every endpoint — paths, methods, parameters, schemas, status codes and auth. Tools consume it to render docs, generate client stubs, mock the API, or run contract tests.

Name resources with plural nouns, not verbs — /orders, /orders/42/items. The verb is the HTTP method, so avoid /getOrder. Nest to show ownership but stay shallow; beyond that, link by id. Use lowercase with hyphens and keep the collection/item pattern predictable.

Headers carry message metadata, separate from the body. Request headers include Authorization (credentials) and Accept (desired format). Key REST response headers are Content-Type (the format), Location (URL of a new resource, with 201), and ETag (a version tag for caching).

Path parameters identify a specific resource in the path — /orders/42 addresses one order. Query parameters refine a collection request — filtering, sorting and pagination like ?status=paid&page=2. Mandatory identifiers go in the path, optional modifiers in the query.

Resources are nouns — /books, /cart/items, /orders. GET /books lists (200), POST /cart/items adds (201), DELETE /cart/items/{id} removes (204), POST /orders checks out (201 with Location). Return 404 for a missing book, 409 for an empty cart, 422 for bad data. Checkout is POST — a non-idempotent create.

POST is not idempotent, so a retry can create a duplicate. The client sends a unique idempotency key in a header; the server stores it with the first response and, on a retry, returns that stored result instead of acting again. Keys live in a fast store with a TTL.

Duplicates arise when a non-idempotent create (POST) is retried after a timeout or double-click — the request succeeded but the client never saw the response. The fix is an idempotency key the backend records, so a repeated key returns the original result.

Prefer cursor (keyset) pagination — the client sends an opaque cursor for the last row seen and gets the next slice plus a nextCursor. Offset/limit degrades at high offsets — the DB scans and discards every skipped row, so page 10 000 is slow. It also skips or repeats rows on inserts, since offsets shift.

Return a 4xx client error, not a 5xx — nothing broke server-side. 422 fits — the request is well-formed but the card is expired. The body carries a machine code (card_expired), a message and the field. The client must not auto-retry the same card; it should ask the user for a new one.

REST is an architectural style over HTTP — recommendations, not a protocol like SOAP. Its constraints are client–server separation, statelessness, cacheability, a uniform interface of resources and standard verbs, a layered system, and optional code-on-demand.

SOAP is a strict XML protocol with XSD/WSDL contracts — formal but heavy. REST is a style over HTTP with standard verbs — simple and ubiquitous. gRPC uses protobuf over HTTP/2 with streaming — fast backend-to-backend. GraphQL queries one endpoint.

The server runs whatever handler you wire, but you break the verbs' contract. GET is safe and cacheable, so proxies and crawlers may prefetch or repeat it — a GET that creates data fires side effects and may be cached wrongly. POST is uncached, so reading with it loses caching. Verbs must mean what they say.

Strategies — URI versioning (/v2/orders), a custom header, or media-type in Accept; URI is simplest, headers stay clean. Adding optional fields or endpoints is backward-compatible — clients ignore what they don't know. Removing or renaming a field, retyping, or tightening validation is breaking, forcing a new version.

Make it asynchronous. POST /reports starts the job, returning 202 with Location at /reports/{id}. The client polls GET /reports/{id}, getting 200 with a status (pending/running/done) while it builds. When ready it returns the result or a 303 to the result resource. This survives the gateway timeout.

Return the right status class plus a consistent JSON body — a stable machine code, a human message, optional field details. Validation → 422 (fix input); missing → 404; auth → 401/403 (re-auth); transient → 503 with Retry-After (retry with backoff). The code drives client logic; the class says who is at fault and whether a retry helps.

JSON is a text exchange format (json-schema describes its structure). YAML is human-readable, common in configs and specs. XML is verbose markup; XSD defines the allowed structure of an XML document, and WSDL describes a SOAP service's operations.

Richardson rates REST maturity in four levels. Level 0 — one URI, one verb. Level 1 — many resources, each a URI. Level 2 — proper verbs and status codes, where most APIs sit. Level 3 adds HATEOAS — responses embed links for the next actions, so the client navigates by those links.