termEngineering & architecture

Application Programming Interface (API)

A defined interface through which software components request capabilities or exchange data without depending on each other's internal implementation.

Download Markdown (.md)

01What it means

An application programming interface (API) is a documented boundary that lets one software component interact with another through specified operations, inputs, outputs, and rules. APIs can exist within a programming language, operating system, library, or network service; a web API is one form, not the whole category.[1][2]

Documented software boundary Consumers use a contract without knowing the provider's internals
  1. ConsumerCalls an operation
  2. API contractInputs, outputs, errors, rules
  3. ProviderHides implementation details

Result or documented error

A web API is one kind of API; every interface needs explicit operations, errors, constraints, and compatibility rules.

02Why it matters

A stable API lets teams and products integrate while changing their internal code independently. Its contract shapes developer experience, security, compatibility, support cost, and the speed at which clients can adopt a capability.

03When to use it

Define an API when a capability needs a clear reusable boundary for another component, team, partner, or customer. A direct internal function or a manual exchange may be simpler when there is only one tightly coupled use and no need for independent evolution.

04How it works

  1. Identify the consumers, tasks, data, trust boundaries, and service expectations the interface must support.
  2. Define operations, inputs, outputs, errors, authentication, and usage constraints as a contract.
  3. Implement the provider behind the contract and expose the interface through an appropriate protocol or language mechanism.
  4. Let consumers call the interface without requiring knowledge of the provider's internal implementation.
  5. Monitor usage and failures, then evolve the contract with explicit compatibility and deprecation policies.

05A practical example

Example

A delivery platform exposes an API that lets a retailer quote shipping, create a parcel, and retrieve tracking events. The retailer integrates against documented requests and responses while the delivery company changes routing systems behind the interface without forcing a client rewrite.

06Where it breaks

An API does not remove coupling; consumers still depend on its behavior, availability, data meanings, and change policy. Poor boundaries leak internal models, and public interfaces create lasting security, documentation, support, and compatibility obligations.

Common mistakes

  • Using API to mean only a public HTTP service and overlooking local or private interfaces.
  • Exposing database structures directly instead of designing around consumer tasks and stable concepts.
  • Documenting successful calls while omitting errors, limits, authentication, and lifecycle expectations.
  • Making breaking changes without versioning, migration support, or a deprecation period.

07Sources

  1. APIMDN Web Docs · Official technical documentationAPI
  2. OpenAPI SpecificationOpenAPI Initiative · Technical specificationOpenAPI Specification
View saved topics

Start typing to search titles, definitions, categories, and frameworks.