REST

Paths name things, not actions: nouns, usually plural collections (/users, /users/42/orders). The HTTP method supplies the verb, so POST /users beats POST /createUser. Verbs in paths duplicate the method and multiply near-identical endpoints.

Path carries identity and hierarchy — what resource you are addressing; it is required and usually part of a single thing's URL. Query carries modifiers on a collection — filtering, sorting, pagination, field selection; these are optional and any combination is valid.

Nest when the child is owned by the parent, has no meaning or identity outside it, and is always accessed through it. Use a top-level collection with a filter when the child is independently identifiable and queried across parents. Many APIs do both: nested for creation and scoped listing, a canonical top-level URI for the item itself.

A resource is anything worth naming with a URI and giving a representation — driven by what clients need to address, not by storage. Entities usually become resources, but resources also cover projections, computed views, and processes that no table matches, and one entity may back several resources.

Three mainstream options: POST a state-transition sub-resource (POST /orders/{id}/cancellation), PATCH the status field, or an explicitly-marked custom method (POST /orders/{id}:cancel). Prefer the sub-resource when the action has its own data or history; keep POST for anything with side effects.

Safe means the request does not change server state - GET and HEAD. Idempotent means doing it N times leaves the same state as doing it once - GET, HEAD, PUT and DELETE. POST and PATCH are neither by default. Safe implies idempotent.

POST creates a resource or runs a process; the server picks the URL and repeating it repeats the effect. PUT sends the complete new representation to a URL you already know; repeating it is harmless. PATCH sends only the fields to change.

201 plus a Location header when the request created a new resource; 200 with a body when you have something useful to return; 204 when the operation succeeded and there is genuinely nothing to send. Deletes typically return 204.

A timeout hides whether the server applied the request. PUT and DELETE describe an end state, so reapplying converges to the same result. POST creates something new each time, so a retry after a lost response creates a duplicate.

PUT-as-upsert makes creation idempotent: the client generates the id (usually a UUID), so a retried request lands on the same URL and cannot create a duplicate. Return 201 when it created, 200 or 204 when it replaced.

Two different things. Resource state is the durable data the API manages - orders, users - and storing it is the point of the API. Application state is per-client context between requests, like where you are in a flow. Statelessness forbids only the second.

Cookies are attached automatically by the browser to matching requests, which is convenient and allows HttpOnly protection from JavaScript, but that automatic sending is what enables CSRF. A Bearer header must be added explicitly by code, so a forged cross-site request carries none - but the token must be stored where script can reach it.

Each request carries everything needed to process it, so no instance holds per-client memory. The load balancer can send any request to any instance and you scale by adding instances. Per-client data in one instance's local memory breaks it.

A self-contained token carries its claims and a signature, so the API validates it locally with no lookup: fast and dependency-free, but the claims are a snapshot valid until expiry. An opaque token is a random string the API must resolve remotely: always current and instantly revocable, at the cost of a call on every request.

Self-contained means the request carries everything needed to process it: credentials, target, and position. For pagination, put the position in the request - an offset or an opaque cursor the server returns to the client - instead of a server-held cursor.

It requires every response to say, implicitly or explicitly, whether it may be reused and for how long. In practice GET and HEAD responses are the cacheable ones; POST responses only with explicit freshness; PUT, PATCH and DELETE responses are never cached.

Use an ETag when you have a cheap exact version (row version, sequence, content hash) or when changes can happen within the same second. Use Last-Modified when a meaningful modification time already exists and human readability or heuristic freshness helps. Emit both when free; emit neither for tiny or per-request-volatile responses.

Pick the TTL from how stale the data may safely be, not from how often it changes. Volatile or personalised resources get seconds or no shared caching; stable reference data gets minutes to hours; immutable, uniquely-addressed content gets a year. Use s-maxage to give shared caches a different, usually longer, value.

A shared cache must not store an authenticated response unless the response explicitly permits shared storage. Safer than tuning directives: separate public resources from per-user ones, put the user identity in the URL path, and mark per-user responses as storable only by that user's own client.

A unique parameter makes a unique cache key, so nothing is ever reused: hit rate is zero and every request reaches the origin. A changing URL is right only in the inverse case — content-addressed or versioned URLs that change when the content changes, allowing very long lifetimes.

Additive: new endpoints, new response fields, new optional request parameters, relaxed validation. Breaking: removing or renaming a field, changing its type, units or format, making a parameter required, tightening validation, changing status codes or the error body shape.

URI path versioning is the most visible, cacheable and easiest to route or test in a browser, but versions the whole API. Header and media-type versioning keep URIs stable and allow per-resource versions, at the cost of discoverability, tooling friction and cache correctness needing Vary.

Return 410 Gone: the resource existed and is intentionally, permanently removed. Include a machine-readable error body naming the version, the removal date and the replacement. Use 301/308 redirects only when the new endpoint is genuinely equivalent.

A tolerant reader ignores unknown fields, reads only what it needs, does not depend on field order, and handles unknown enum values with a default branch instead of failing. That lets the server add fields and values without redeploying clients.

Sunset (RFC 8594) gives an HTTP-date after which the resource becomes unresponsive; Deprecation says it is already or will be deprecated. Pair them with Link rel="sunset" or rel="deprecation" to documentation. Clients should log and alert on them.

A link relation is a short label saying how the target URL relates to the current resource: self is this resource's own URL, next the following page, edit the URL you write to. Registered IANA names give clients a shared vocabulary so generic code can follow links without endpoint-specific rules.

The response advertises the transitions currently available, so the server owns the state machine and the client renders whatever affordances it is given instead of reimplementing the rules. The client still needs to understand each relation's meaning and what payload it takes, and the server still enforces every rule itself.

A HAL resource is ordinary JSON plus two reserved keys. _links maps relation names to link objects with an href (optionally templated, type, title). _embedded maps relation names to full nested resources, so a client gets related data in one response instead of following every link.

Top level holds data, errors or meta. data is a resource object with type, id, attributes and relationships; relationships hold identifier objects (type plus id) and links; included carries the full related resources, deduplicated. It gives you a normalised graph plus fixed conventions for includes, sparse fields and paging.

Level 0: one URL, one verb, the operation named in the body. Level 1: many resource URLs. Level 2: proper HTTP verbs and status codes per resource. Level 3: responses carry hypermedia links telling the client what it can do next.

An envelope wraps the items in an object: data holds the array, meta holds paging info (page size, cursors, counts), and links holds next/prev URLs. A bare array leaves no room to add that without breaking clients.

Use one comma-separated sort parameter where order matters and a leading - means descending: sort=-created_at,name. Whitelist the allowed field names, define a default sort, and always append a unique tiebreaker such as the id.

Omitted: apply a documented default (often 20-50) — never "everything". Over the maximum: either clamp to the max or return 400, but document which. Non-numeric or negative: 400. Echo the effective limit in the response so the client can see what actually applied.

Link carries one or more comma-separated entries of the form <url>; rel="next". Paging uses rel values next, prev, first, last. Clients must parse the header and follow the URLs opaquely, never rebuild them by incrementing a page number.

Bracket suffixes (created_at[gte]=2024-01-01) and RHS prefixes (created_at=gte:2024-01-01) add per-field operators while keeping ordinary query parsing; RSQL/FIQL and OData $filter add a real expression language with AND/OR/grouping, at the cost of a parser, a validator, and unbounded query complexity. Start with the simple forms.

Those details leak your internals to attackers — stack, framework versions, table names, ID ranges — and are useless to callers. Return a stable code, a safe message and a request id; keep the trace server-side in logs, keyed by that id.

It is a standard JSON format for HTTP error bodies, media type application/problem+json. Its members are type (a URI identifying the problem kind), title, status, detail and instance — all optional, plus your own extension members.

Retry-After tells the client how long to wait before trying again. It takes either delay seconds (Retry-After: 120) or an HTTP-date. Send it on 429 and 503, and on 3xx redirects that ask the client to wait.

Return an array of violations, one per failed field. Each entry carries a machine-readable code, a target naming the field, and a human message. Clients switch on the code and attach the message to the right input; a prose string cannot be parsed.

An error body should carry a stable machine-readable code, a human message, and a request id for support. Clients branch on the code; the message is prose that can be reworded or localized without breaking any caller.

The client generates a unique key (usually a UUID) per logical operation and sends it as the Idempotency-Key request header. The server records the key with the result; if the same key arrives again it returns the stored response instead of re-executing. It makes retrying a POST safe.

Store a row keyed by (scope, key) holding a fingerprint of the request, a state (in-progress / completed), and the saved status, headers and body. First request: insert the row, execute, save the response. Repeat: find the completed row and return the stored response without re-executing.

Almost nothing: a timeout means you lost the answer, not that the work did not happen. The request may have been fully applied. Retrying a non-idempotent POST can duplicate the effect, so either make the operation retry-safe first, or reconcile by querying before retrying.

Re-read the resource to get current state and a fresh validator, reconcile the user's intended change against what actually changed, then resend with the new validator. Never blindly resend the same body with a refreshed token, and cap the retry loop.

Reject it without executing anything. The server stores a fingerprint (hash of method, path and body) with each key and compares on every arrival; a mismatch means the client has a bug, so return an error — commonly 422 Unprocessable Content — rather than replaying or executing.