API Glossary: Definitions of Common API Terms

API: An API (application programming interface) is a defined contract that lets one piece of software request data or actions from another without knowing how it is implemented.
API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.
API documentation: API documentation is the reference and guide material that explains how to use an API: its endpoints, parameters, authentication, errors and examples.
API endpoint: An API endpoint is a specific address, usually a URL path combined with an HTTP method, where a client sends requests to perform one operation on an API.
API gateway: An API gateway is a server that sits in front of one or more APIs and handles cross-cutting concerns such as routing, authentication, rate limiting, logging and version routing.
API key: An API key is a secret string a client sends with each API request to identify its application or account for authentication, quotas and billing.
API lifecycle: The API lifecycle is the sequence of stages an API passes through, from design and build to release, versioning, deprecation and eventual retirement.
API mocking: API mocking replaces a real API with a simulated one that returns predefined responses, so teams can build and test clients without the real service.
API monitoring: API monitoring continuously checks that an API is available, fast and returning correct responses in production, and alerts teams when it stops doing so.
API pagination: API pagination splits large result sets into pages that clients fetch one at a time, using offsets, page numbers or opaque cursors.
API SDK: An API SDK (software development kit) is a client library that wraps an API in idiomatic functions and types for a specific programming language.
API security: API security is the practice of protecting APIs from misuse and attack with authentication, authorization, input validation, rate limits and monitoring.
API testing: API testing verifies that an API returns correct responses, status codes, data and performance for given requests, directly at the interface without a UI.
API versioning: API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.
API-first: API-first is a development approach where the API contract is designed and agreed before implementation, and treated as a product in its own right.
Backward compatibility: An API change is backward compatible when every client built against the previous version keeps working, with the same behavior, after the change ships.
Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.
Contract testing: Contract testing verifies that an API provider and its consumers agree on the requests and responses they exchange, so either side can change without silently breaking the other.
CORS: CORS (Cross-Origin Resource Sharing) is a browser mechanism where HTTP headers let a server permit pages from other origins to read its responses.
GraphQL: GraphQL is a query language and runtime for APIs where clients request exactly the fields they need from a typed schema, usually through a single endpoint.
gRPC: gRPC is an open-source remote procedure call framework that uses HTTP/2 and Protocol Buffers to let services call typed methods on each other efficiently.
HTTP status codes: HTTP status codes are three-digit numbers a server returns with each response to signal its outcome, grouped in five classes from 1xx to 5xx.
Idempotency: An API operation is idempotent when performing it multiple times has the same effect as performing it once, which makes retries safe.
JSON Schema: JSON Schema is a declarative vocabulary for describing the structure of JSON data (types, required fields, formats, limits) so documents can be validated.
JSON Web Token (JWT): A JSON Web Token (JWT, RFC 7519) is a compact, URL-safe token of signed JSON claims, widely used as an access or ID token to authenticate API calls.
OAuth 2.0: OAuth 2.0 (RFC 6749) is an authorization framework that lets an app get limited, revocable access to an API on a user's behalf without their password.
OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
Rate limiting: Rate limiting caps how many requests a client can make to an API in a given time window, protecting the service from overload and abuse.
REST API: A REST API is an HTTP API organised around resources identified by URLs and manipulated with standard methods such as GET, POST, PUT, PATCH and DELETE.
Semantic versioning (SemVer): Semantic versioning is a MAJOR.MINOR.PATCH numbering scheme where a major bump signals a breaking change, a minor bump adds backward-compatible features, and a patch fixes bugs.
Sunset header: The Sunset header (RFC 8594) is an HTTP response header that gives the date after which a resource is expected to stop responding.
Webhook: A webhook is an HTTP callback: when an event happens, a provider sends an HTTP request with the event data to a URL the consumer registered.

API glossary

Ship API changes without breaking your customers.