🔌 API Design Language

An HTTP method is idempotent if making the same request multiple times produces the same server state as making it once. PUT and DELETE are idempotent, while POST is not — this distinction matters when designing retry logic, because clients can safely retry idempotent requests after a network failure without risking duplicate side effects.

The three main versioning strategies are URL versioning (e.g., /v1/users), header versioning (Accept: application/vnd.api.v1+json), and query parameter versioning (?version=1). Engineers typically describe URL versioning as the most explicit and cacheable, while header versioning is considered cleaner but harder to test in a browser — the choice is a trade-off between discoverability and coupling.

A breaking change is one that requires existing API consumers to update their code — for example, renaming a required field, changing a response status code, or removing an endpoint. A non-breaking change, also called a backward-compatible change, adds new optional fields or endpoints without altering existing contract behaviour.

Contract-first design means defining the API specification (typically in OpenAPI/Swagger) before writing any implementation code. Teams use phrases like "we design the contract in OpenAPI, then generate stubs" or "the spec is the source of truth" to describe this approach, which enables parallel frontend and backend development against a shared interface definition.

Offset pagination uses a page number and page size (e.g., ?page=3&size=20) and is simple to implement but becomes inconsistent when data changes between requests. Cursor pagination uses an opaque pointer to the last seen item (e.g., ?after=abc123) and is more stable for real-time feeds — engineers describe it as "stable pagination" because inserting or deleting records does not shift subsequent pages.

A deprecation notice announces that an API endpoint or field will be removed in a future version, giving consumers time to migrate. Standard vocabulary includes the sunset date (the date the feature will be removed), a migration guide (instructions for moving to the replacement), and a Deprecation or Sunset HTTP header that machines can parse to automate alerts.

Content negotiation is the mechanism by which a client and server agree on the format of a response. The client signals its preferred format using the Accept header (e.g., Accept: application/json), and the server responds with the Content-Type header confirming what it returned. This allows a single endpoint to serve JSON, XML, or other formats without requiring separate URLs.

Rate limiting restricts how many requests a client can make within a time window to protect the API from abuse and ensure fair usage. Engineers typically communicate rate limits via response headers such as X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After, and describe policies using phrases like "100 requests per minute per API key" or "exponential backoff on 429 responses".

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint where API responses include links that guide clients through available actions, rather than requiring clients to construct URLs themselves. In design reviews, engineers debate whether the added complexity of embedding links justifies the loose coupling benefit, often concluding it is most valuable for public APIs with diverse unknown clients.

Authentication is the process of verifying who a caller is (typically via an API key, OAuth token, or JWT), while authorisation determines what that caller is permitted to do. In API design discussions, teams use phrases like "we authenticate at the gateway and authorise at the service level" or "this endpoint requires the write:orders scope" to describe the separation of concerns.