API

The term covers two different layers. A library or operating-system API (POSIX, Win32, a language's standard library) is a source-level contract resolved at compile or link time, and it is distinct from the ABI, the binary contract of calling conventions and data layout that decides whether compiled code still links after an upgrade. A network API is a contract over a wire protocol. On the web the dominant styles are resource-oriented REST over HTTP, RPC styles such as gRPC (Protocol Buffers over HTTP/2) and JSON-RPC 2.0, GraphQL with a single endpoint and client-chosen selection sets, and event-driven interfaces such as webhooks. Contracts are written down in machine-readable form: OpenAPI documents for HTTP APIs, .proto files for gRPC, the GraphQL schema definition language, AsyncAPI for event interfaces.

Evolving an API without breaking its consumers is the central engineering problem. Adding optional fields is compatible only if clients ignore unknown fields (the tolerant reader pattern); removing, renaming or changing the type of a field breaks them. Providers version in the path (/v2), in a header or in the media type, and signal retirement with the Sunset header (RFC 8594). Hyrum's law captures the limit of all contracts: with enough users, every observable behaviour, including undocumented ordering or error text, will be depended on by someone. Operational semantics belong to the contract too: pagination, rate limits answered with 429 Too Many Requests (RFC 6585) and Retry-After, and idempotency keys that make retries of non-idempotent POST requests safe.

The OWASP API Security Top 10 (2023 edition) shows where APIs fail: API1 Broken Object Level Authorization, where the server accepts an object ID from the client without checking ownership; API3 Broken Object Property Level Authorization, covering mass assignment and excessive data exposure; API5 Broken Function Level Authorization; API4 Unrestricted Resource Consumption; and API9 Improper Inventory Management, meaning forgotten old versions and undocumented "shadow" endpoints. Authentication ranges from API keys, which identify an application but rarely a user and tend to leak, through OAuth 2.0 bearer tokens (RFC 6750) and JWT access tokens that must be validated for issuer, audience and expiry, to mutual TLS with certificate-bound tokens (RFC 8705).

An API should not be confused with its neighbours: a protocol (HTTP) is the transport the API uses, an endpoint is one addressable operation within it, an SDK is a client library wrapping it, and an API gateway is infrastructure in front of it that handles routing, authentication and rate limiting, but cannot enforce object-level authorisation, which requires business knowledge only the API itself has.