The API as a Product

An API has users. Its users are developers.

Developers use an API to complete a task. They need to understand its behavior, handle mistakes, and decide whether they can depend on it. They may never speak to the team that built it.

A useful API helps a developer find an operation, send a valid request, understand the response, recover from errors, and adapt to changes. It should not require the developer to ask its authors about every important behavior.

Four qualities make that possible: consistency, useful errors, fast onboarding, and responsible deprecation