API Design

A specific URL path on a server that handles requests for a given resource or action. Each endpoint represents a single capability of the API: GET /users returns a list; POST /users creates one.

"We deprecated the /v1/users endpoint and migrated all clients to /v2/users — the new endpoint returns paginated results with cursor-based navigation."

The verb in an HTTP request that indicates the intended action. GET: read data. POST: create a resource. PUT: replace a resource entirely. PATCH: partially update. DELETE: remove. OPTIONS / HEAD: metadata operations.

"Our API uses PATCH instead of PUT for partial updates — the client only sends the fields that changed, not the entire resource, which saves bandwidth and avoids overwriting concurrent edits."

A 3-digit number in the HTTP response indicating the outcome. 2xx: success. 3xx: redirect. 4xx: client error. 5xx: server error. Key ones: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Server Error.

"We return 422 Unprocessable Entity when the request is syntactically valid JSON but fails business validation — for example, a negative price value — rather than the generic 400 Bad Request."

The data body of an HTTP request or response. In a POST or PATCH request, the payload contains the data to create or update. In a response, the payload is the returned resource or result. Usually JSON, sometimes XML or binary.

"Keep payload size in mind for mobile clients — our search endpoint returns a full payload by default, but supports a ?fields= parameter to return only the fields the client needs."

Authentication (AuthN): verifying who the caller is (identity). Authorisation (AuthZ): verifying what the caller is allowed to do (permissions). Common confusion: a request can be authenticated but not authorised — 401 vs 403.

"401 Unauthorized means the request is not authenticated — no valid token. 403 Forbidden means authenticated but not authorised — the user exists but lacks the permission to access that resource."

A secret token passed in a request header or query parameter to identify and authenticate the calling application. Simpler than OAuth but less secure — keys do not expire automatically and cannot be scoped to a user identity.

"We rotate API keys every 90 days and track usage per key — if a key generates anomalous traffic, we can revoke it immediately without affecting other integrations."

Bearer token: a credential sent in the Authorization header (Authorization: Bearer <token>). JWT (JSON Web Token): a self-contained, base64-encoded token carrying claims (user ID, roles, expiry). The server verifies the signature without a database lookup.

"We use short-lived JWTs (15-minute expiry) for API access and a separate long-lived refresh token for obtaining new JWTs — this limits the blast radius of a stolen access token."

Controlling the number of API requests a client can make in a given time window (e.g., 100 requests per minute). Protects the server from overload and abuse. Exceeded limits return 429 Too Many Requests with a Retry-After header.

"Our public API is rate-limited at 60 requests/minute per API key. The X-RateLimit-Remaining header tells clients how many requests they have left in the current window."

Splitting large result sets into pages. Offset-based: LIMIT 20 OFFSET 40 — simple but slow on large datasets. Cursor-based: next_cursor token from the previous response — performant but non-random-access. Page-based: ?page=3&size=20.

"We migrated from offset-based to cursor-based pagination for the activity feed — offset pagination was causing slow queries on pages 500+ as the database had to skip millions of rows on each request."

A property of an operation: calling it multiple times produces the same result as calling it once. GET, PUT, and DELETE are idempotent. POST is typically not (each call creates a new resource). Idempotency keys allow POST requests to be made idempotent.

"Our payment endpoint requires an Idempotency-Key header — if the client retries after a network timeout, we return the original response instead of charging the card twice."

Managing multiple versions of an API so old clients continue working when new versions are released. Common strategies: URI versioning (/v1/users, /v2/users), header versioning (Accept: application/vnd.api+json;version=2), query parameter (?version=2).

"We use URI versioning — it is explicit, easy to test in a browser, and cacheable by CDN. When we introduce a breaking change, we ship /v2/ while keeping /v1/ alive for 12 months with a deprecation notice."

An API change that is not backward compatible — it will break existing clients unless they update their code. Examples: removing a field, renaming an endpoint, changing a field type, requiring a new mandatory parameter.

"Renaming the user_id field to id is a breaking change — all existing clients will fail when they look for user_id in the response. We kept both fields during a 6-month deprecation window."

An event-driven HTTP callback — instead of the client polling for updates, the server sends a POST request to a client-registered URL when an event occurs. Commonly used for payment notifications, CI/CD triggers, and third-party integrations.

"We use webhooks for payment status updates — Stripe calls our /webhooks/payment endpoint when a charge succeeds or fails, which is more efficient than polling the payment status every second."

OpenAPI Specification (formerly Swagger): a machine-readable format (YAML/JSON) for describing REST API endpoints, parameters, request/response schemas, and authentication. Swagger UI auto-generates interactive documentation from an OpenAPI file.

"All our internal APIs must have an OpenAPI spec checked into the repository — it serves as the contract between frontend and backend teams, and is used to auto-generate TypeScript client types."

A query language for APIs (developed by Meta) where the client specifies exactly what data it needs in a single request. Eliminates over-fetching (too much data) and under-fetching (not enough data, requiring multiple requests). Has a strongly typed schema.

"We moved the mobile app to GraphQL for the home feed — instead of 4 REST calls to assemble one screen, the client sends one query asking for exactly the fields it displays, reducing payload size by 70%."