Field Guide · concept

Also known as: API "application programming interface"

An API (application programming interface) is a defined contract through which one piece of software exposes its capabilities to another, hiding its implementation behind a stable set of operations.1

client calls APIcontract implementation(hidden)
An API is the published contract a client calls; the provider's implementation stays hidden behind it.

What an API is

An API is a form of abstraction: it specifies what a component does — the operations, their inputs and outputs, and the rules for using them — without revealing how it does it. That separation lets the provider change the implementation freely as long as the contract holds, and lets the consumer build against a stable surface. APIs come in several flavors:

  • Library / package APIs — the public functions, types, and methods a code library exposes to programs that import it.
  • Operating-system APIs — the system calls a program uses to talk to the kernel.
  • Web APIs — operations a service exposes over the network, commonly in the REST style over HTTP, or via GraphQL or gRPC.1

A good API is small and role-focused (the interface segregation idea), consistent, and clear about how it reports failures — its error-handling contract is part of the interface.

Why APIs matter

APIs are the seams that let large systems be built from independently developed parts. Because callers depend only on the contract, an API reduces coupling between components and teams. That stability is also a promise: once others build on your API, changing it can break them, which is why backward compatibility and semantic versioning matter so much — a major version bump signals a breaking change to the contract. The same discipline governs the public surface of a reusable library distributed through a package manager.

Sources

  1. API — Wikipedia, for the contract definition and the kinds of API (library, OS, web).  2

See also