API (Application Programming Interface)

An API is the contract through which one piece of software is invoked by another, defining operations, inputs, outputs, and error semantics. A well-designed web API is consistent, evolvable, and explicit about versioning and failure modes. REST, gRPC, and GraphQL are the dominant styles for networked APIs.

Affordance (Hypermedia)

An affordance is an action a client can take on a resource, advertised by the server as a link or form in the response rather than hardcoded by the client. Hypermedia-driven APIs (HATEOAS) expose affordances so clients discover available transitions at runtime. This decouples the client from server URL structure at the cost of more complex client logic.

Bearer Token

A bearer token is a credential whose mere possession grants access, sent in the Authorization: Bearer header. Because anyone holding it can use it, bearer tokens must be transmitted only over TLS, kept short-lived, and never logged. OAuth 2.0 access tokens and JWTs are commonly used as bearer tokens.

Backward Compatibility

An API change is backward compatible if existing clients keep working without modification after it ships. Adding optional fields, new endpoints, or new enum-tolerant values is typically safe; removing fields, renaming them, or tightening validation usually breaks clients. Semantic Versioning encodes the breaking-vs-safe distinction in the MAJOR version.

Caching (HTTP)

HTTP caching lets responses be reused without contacting the origin again, controlled by Cache-Control, Expires, ETag, and Last-Modified. A response marked Cache-Control: public, max-age=3600 may be stored by shared and private caches for an hour. Correct caching reduces latency and load but requires careful invalidation and Vary handling.

Conditional Request

A conditional request applies an HTTP method only if a precondition holds, using headers such as If-None-Match (with an ETag) or If-Modified-Since. It powers efficient caching (a 304 Not Modified skips the body) and optimistic concurrency (If-Match rejects a stale update with 412 Precondition Failed).

Content Negotiation

Content negotiation is the mechanism by which a client and server agree on the representation of a resource, driven by Accept, Accept-Language, and Accept-Encoding request headers and the Content-Type response header. A server may return JSON or XML for the same resource depending on the client's Accept header, responding 406 Not Acceptable if it cannot satisfy the request.

CORS is a browser security mechanism that lets a server declare which other origins may read its responses via headers such as Access-Control-Allow-Origin. For non-simple requests the browser first sends a preflight OPTIONS request, and the server must respond with the allowed methods and headers. CORS protects users, not the server, and is enforced only by browsers.

CRUD

CRUD stands for Create, Read, Update, Delete - the four basic operations over persistent data, mapped in REST to POST, GET, PUT/PATCH, and DELETE respectively. It is a useful shorthand for the scope of a resource-oriented service. Not every API is CRUD; some are better modelled as commands or events.

Cursor Pagination

Cursor (keyset) pagination returns a page of results plus an opaque cursor pointing just past the last item, which the client sends back to fetch the next page. Unlike offset pagination it stays correct and efficient when items are inserted or deleted between requests, because it seeks by a stable sort key rather than skipping a row count.

Deprecation

Deprecation is the formal signalling that an API element will be removed, giving clients time to migrate before it disappears. The IETF Deprecation and Sunset HTTP headers (RFC 9745 and RFC 8594) communicate the status and removal date in responses. A deprecation should always come with a migration path and a documented timeline.

DELETE

DELETE is the HTTP method that requests removal of the target resource. It is idempotent - deleting the same resource twice leaves the same end state - though the second call commonly returns 404 Not Found while the first returns 200 OK or 204 No Content. DELETE is not safe, because it changes server state.

Endpoint

An endpoint is a specific URL plus HTTP method that a client can call, such as GET /v1/orders/{id}. In resource-oriented design endpoints expose nouns (resources) and use HTTP methods as the verbs. Grouping related endpoints under a consistent path hierarchy is central to a discoverable API.

ETag

An ETag (entity tag) is an opaque identifier a server assigns to a specific version of a resource representation, returned in the ETag response header. Clients use it in If-None-Match for cache validation and If-Match for optimistic concurrency. A strong ETag guarantees byte-for-byte equality; a weak ETag (prefixed W/) only guarantees semantic equivalence.

Fan-out / Aggregation

Fan-out is the pattern where a single client request triggers calls to several downstream services, whose responses are aggregated into one. An API gateway or backend-for-frontend often performs aggregation to reduce client round trips. The risk is that overall latency and failure probability grow with the number of downstream calls.

GET

GET is the HTTP method that retrieves a representation of the target resource without changing it. It is both safe (no side effects) and idempotent, which makes responses cacheable and requests freely retryable. A GET must never carry a request body that affects the result and should not be used to trigger state changes.

GraphQL

GraphQL is a query language and runtime for APIs where the client specifies exactly which fields it needs in a single request to one endpoint, typically POST /graphql. It eliminates over- and under-fetching but shifts complexity to the server (query cost analysis, N+1 resolution) and complicates HTTP caching, which is keyed on URLs.

gRPC

gRPC is a high-performance RPC framework using HTTP/2 for transport and Protocol Buffers for typed, binary message serialization. It supports unary and streaming calls and generates client/server stubs from a .proto contract. It excels for low-latency internal service-to-service communication but is less browser-friendly than REST/JSON.

HATEOAS

HATEOAS (Hypermedia As The Engine Of Application State) is the REST constraint that responses include links describing the available next actions, so clients navigate the API by following links rather than constructing URLs. It is the least adopted REST constraint in practice. Done well it lets servers evolve URL structures without breaking clients.

Idempotency

An operation is idempotent if performing it multiple times has the same effect on server state as performing it once. GET, PUT, and DELETE are defined to be idempotent; POST generally is not. To make an unsafe create operation safe to retry, clients send an idempotency key the server deduplicates on.

Idempotency Key

An idempotency key is a unique, client-generated value (often a UUID) sent in a header such as Idempotency-Key so the server can recognise and ignore a retried request, returning the original result instead of acting twice. It is essential for safely retrying non-idempotent operations like payments after a network timeout. The server stores the key and its first response for a bounded window.

JSON:API

JSON:API is a specification that standardises how to format JSON request and response documents, covering resource objects, relationships, included data, pagination, filtering, and errors. Adopting it removes bikeshedding over envelope shape and gives clients predictable structure. Its rigidity can feel heavyweight for simple internal APIs.

JWT (JSON Web Token)

A JWT is a compact, URL-safe, signed (and optionally encrypted) token carrying claims as a JSON payload, defined by RFC 7519. APIs use signed JWTs as stateless access tokens, verifying the signature instead of a database lookup. Because the payload is only base64url-encoded (not encrypted by default), never put secrets in a JWT and always validate exp, iss, and aud.

Media Type

A media type (MIME type) labels the format of a representation, such as application/json or application/problem+json, carried in Content-Type and Accept. Vendor and versioned media types like application/vnd.example.v2+json enable media-type-based API versioning. The media type tells the recipient how to parse the body.

OpenAPI

OpenAPI is a language-agnostic specification for describing HTTP APIs in a machine-readable document (YAML or JSON), formerly known as Swagger. From one OpenAPI document teams generate documentation, client SDKs, server stubs, mock servers, and contract tests. Treating the OpenAPI file as the source of truth is the core of a design-first workflow.

OAuth 2.0

OAuth 2.0 is an authorization framework (RFC 6749) that lets a third-party application obtain limited access to a resource on a user's behalf without sharing the user's credentials. It defines grant flows such as Authorization Code (with PKCE) for user-facing apps and Client Credentials for service-to-service access. OAuth handles authorization; authentication of the user is layered on with OpenID Connect.

Offset Pagination

Offset pagination returns a window of results using limit and offset (or page and size) parameters, skipping offset rows before returning limit rows. It is simple and allows jumping to an arbitrary page, but becomes slow on large offsets and can skip or duplicate rows when the underlying data changes between requests.

PATCH

PATCH is the HTTP method that applies a partial modification to a resource, sending only the fields to change rather than a full representation. It is not guaranteed to be idempotent in general, though a given patch document can be designed to be. Common formats are JSON Merge Patch (RFC 7386) and JSON Patch (RFC 6902).

PUT

PUT is the HTTP method that creates or fully replaces the target resource with the representation in the request body. It is idempotent: sending the same PUT repeatedly yields the same final state. Use PUT when the client controls the resource identifier and supplies a complete representation; use POST when the server assigns the identifier.

POST

POST is the HTTP method that submits data to be processed by the target resource, most often to create a subordinate resource under a collection. It is neither safe nor idempotent, so repeating it can create duplicates unless an idempotency key is used. A successful create typically returns 201 Created with a Location header pointing to the new resource.

Problem Details (RFC 9457)

Problem Details is a standard JSON (and XML) format for HTTP error responses, defined by RFC 9457 (which obsoletes RFC 7807), using the application/problem+json media type. A problem document carries type, title, status, detail, and instance members plus extensions. Standardising errors lets clients handle failures uniformly across APIs.

Rate Limiting

Rate limiting caps how many requests a client may make in a time window to protect a service from overload and abuse. Servers signal limits with RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers and reject excess traffic with 429 Too Many Requests, ideally including a Retry-After header. Token bucket and sliding window are common algorithms.

REST (Representational State Transfer)

REST is an architectural style for networked applications defined by Roy Fielding, built on constraints including client-server, statelessness, cacheability, a uniform interface, and layered system. A RESTful API models resources addressable by URLs and manipulated through standard HTTP methods and representations. Most "REST APIs" satisfy some but not all constraints, especially HATEOAS.

Resource

A resource is any named thing an API exposes - an order, a user, a collection of invoices - identified by a URI and manipulated through representations. In REST design, resources are nouns and HTTP methods are the verbs that act on them. Modelling the right resources and their relationships is the central design activity.

Richardson Maturity Model

The Richardson Maturity Model grades a REST API on three levels above the baseline: Level 1 introduces resources, Level 2 uses HTTP verbs and status codes correctly, and Level 3 adds hypermedia controls (HATEOAS). It is a useful heuristic for assessing how RESTful an API is, though level 3 is rarely required in practice.

Safe Method

A safe HTTP method is one that does not change server state and is intended only for retrieval, namely GET, HEAD, and OPTIONS. Safety lets intermediaries cache and prefetch responses freely. A method that mutates state must never be exposed as a safe method, regardless of how it is named.

Schema (API)

An API schema is a formal, machine-readable description of the shapes of requests and responses, such as a JSON Schema, an OpenAPI components section, or a Protocol Buffers message. Schemas enable validation, code generation, and contract testing. Publishing and versioning the schema turns an informal API into a verifiable contract.

SDK (Software Development Kit)

An SDK is a client library that wraps an API's HTTP calls behind idiomatic functions in a given language, handling auth, retries, pagination, and serialization. SDKs improve developer experience and can be generated from an OpenAPI document. The risk is drift between hand-written SDKs and the underlying API contract.

Status Code

An HTTP status code is a three-digit number in the response that signals the outcome of a request, grouped into 1xx informational, 2xx success, 3xx redirection, 4xx client error, and 5xx server error. Using the semantically correct code (for example 201, 400, 404, 409, 429) lets generic clients and intermediaries behave correctly. Misusing 200 for errors breaks this contract.

Statelessness

Statelessness is the REST constraint that each request carries all the information needed to process it, with no client session state stored on the server between requests. It makes any server instance able to handle any request, which simplifies horizontal scaling and failover. Application state lives on the client or in shared stores, not in server memory.

Swagger UI

Swagger UI is a tool that renders an OpenAPI document as interactive, browsable documentation where developers can read endpoint definitions and execute live "try it out" requests. It is commonly served alongside an API to provide always-current, contract-derived docs. It is one of several tools in the OpenAPI ecosystem.

TLS (Transport Layer Security)

TLS is the cryptographic protocol that encrypts and authenticates HTTP traffic, turning http into https. APIs must be served exclusively over TLS so credentials, tokens, and payloads cannot be intercepted or tampered with. Modern practice mandates TLS 1.2 or 1.3 and rejects plaintext HTTP, often via HSTS.

Throttling

Throttling is the act of deliberately slowing or rejecting requests once a client exceeds an allowance, the enforcement side of rate limiting. A throttled client receives 429 Too Many Requests and should back off, ideally honouring the Retry-After header. Graceful throttling protects shared capacity and gives fair access under load.

URI Versioning

URI versioning encodes the API version in the path, such as /v1/orders, making the version explicit and easy to route and cache. It is the most common versioning scheme because it is visible and unambiguous, at the cost of changing every URL on a major bump. Alternatives include header and media-type versioning.

Webhook

A webhook is a server-to-server HTTP callback: instead of a client polling for changes, the API pushes an event to a client-supplied URL when something happens. Robust webhooks include a signature (e.g. HMAC) for verification, retries with backoff, and an event ID for idempotent consumption. They invert the usual request direction and require the receiver to expose an endpoint.

429 Too Many Requests

429 Too Many Requests is the HTTP status code a server returns when a client has sent too many requests in a given time window, the standard response to a rate-limit breach. It should include a Retry-After header telling the client when to retry. Clients should treat 429 as a signal to back off, not to hammer harder.