An application programming interface (API) is a defined boundary through which software components communicate and access capabilities or data. A web API lets applications call remote operations over a network, commonly using HTTP, without knowing the provider’s implementation. APIs can connect mobile or web applications to backends, server applications to one another, or internal systems to external partners. section 1.1 section 1.1.1
An API separates what consumers can request from how the provider fulfills it. Consumers send requests describing an action and its data; providers return responses describing the result. This boundary hides databases, microservices, algorithms, and other implementation details, allowing clients to change independently. section 1.1.2 section 1.1.3
API design determines how effectively the boundary serves its consumers:
- Private APIs connect applications and teams inside an organization; partner APIs serve selected external organizations; public APIs are available broadly. section 1.1.4
- A useful API meets consumer needs, works across contexts, supports interoperability, and avoids exposing unnecessary data or operations. section 1.2.5 section 1.7.1
- Design applies to new APIs and modifications, preferably after deciding why the API is needed and before implementation begins. section 1.3
- REST is one HTTP-based style; SOAP, GraphQL, and gRPC use HTTP differently, so the API type should match the capabilities and context. section 1.1.2 section 1.6.2
A social network API
A mobile application sends a photo and message to a backend’s Share operation. The backend processes and stores the message, while other applications retrieve it through a Timeline operation. The clients need neither the database structure nor the face-detection algorithm; they need only the agreed request and response behavior. section 1.1.1 section 1.1.3
Figure 1.1 The SOCNET web API exposed by the backend has operations that can be called by any kind of application over the internet. The Friends and Messages internal applications also expose web APIs that can be called over the local network.
Trace how one backend API exposes operations to mobile, web, health-check, and internal applications across internet and local-network boundaries. section 1.1.1
