An API (application programming interface) defines the functions and protocols that let software systems communicate and exchange information across a shared boundary. Common forms include REST, SOAP, RPC, GraphQL, and WebSocket APIs. section 1.3
An API can expose business capabilities externally or technical capabilities internally, such as an internal Permissions API. When it is managed around consumer problems, value, documentation, support, and continuous improvement, it becomes an API product rather than merely an integration interface. section 1.3
Treat API quality as both a technical and organizational concern:
- Define the consumer value proposition before optimizing the interface. section 5.3.4
- Support developers with documentation, onboarding, authentication mechanisms, sandbox environments, SDKs, management platforms, and developer portals. section 5.3.4
- Apply automated checks broadly, then reserve costly human design reviews primarily for public, partner, or potentially external-facing APIs. section 5.3.4
- Use lightweight asynchronous review for small, style-conforming changes; escalate broad API surface-area changes or complex design decisions to a meeting. section 5.1
Figure 1.2 An API product is a packaged API solution that provides a core problem-solving benefit to an API consumer. It has nine components, including good documentation and support channels, and an API team that oversees its life cycle.
Use the API product model to inspect how consumer value, documentation, support, lifecycle ownership, and service commitments surround the interface itself. section 1.3
