An application programming interface (API) defines how computer systems interact. It exposes functionality or data through a contract while separating users from implementation details. APIs can be local libraries, code interfaces, or web APIs exposed over a network. section 1.0 section 1.1
Web APIs give builders control over a shared service, but consumers have little control over changes or outages. Unlike a downloaded library, a web API can change behavior remotely and immediately affect dependent applications. section 1.1
Use the figure to compare how web API consumers experience implementation changes, including changed behavior or a disabled service. section 1.1
APIs matter because computers need stable, nonvisual interfaces rather than graphical layouts. They also enable composition: applications can assemble API functionality as reusable building blocks. section 1.2
A useful API should:
- Expose functionality users want to access programmatically, rather than merely offering a human-facing application. section 1.4
- Express user intent clearly and simply through operations such as TranslateText() or DetectLanguage(). section 1.4.2
- Avoid forcing users into workarounds that repurpose an operation to reach unsupported or hidden functionality. section 1.4.2
- Remain operational, simple, predictable, and compatible as it evolves. section 1.2 section 1.5
An expressive translation API
A translation service should provide a direct TranslateText operation with explicit inputs such as source text and target language. If users instead call TranslateText repeatedly to detect a language, the interface is exposing capability without expressing the user's real intent. section 1.4.2
Treat an API as a long-lived contract: identify the programmatic capability users need, expose it through clear operations, and prefer predictable evolution over changes that force clients to relearn the interface. section 1.4 section 1.5
