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)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/application-programming-interface/
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]
- ConsumerCalls an operation
- API contractInputs, outputs, errors, rules
- 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
- Identify the consumers, tasks, data, trust boundaries, and service expectations the interface must support.
- Define operations, inputs, outputs, errors, authentication, and usage constraints as a contract.
- Implement the provider behind the contract and expose the interface through an appropriate protocol or language mechanism.
- Let consumers call the interface without requiring knowledge of the provider's internal implementation.
- Monitor usage and failures, then evolve the contract with explicit compatibility and deprecation policies.
05A practical 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.