API design playbook

An application programming interface, or API, is the contract that lets one piece of software ask another for data or an action. The playbook circulating this month reduces that contract to a few rules: keep names and behavior consistent, model things as resources, version changes, and return errors developers can act on. (github.com) (learn.microsoft.com) Resource-oriented design means the API is built around nouns like users, orders, or invoices, with a small set of standard actions layered on top. Google’s API guidance says that pattern favors many clearly named resources and a limited set of methods such as Get, List, Create, Update, and Delete. (google.aip.dev 1) (google.aip.dev 2) That approach is meant to make an API guessable before a developer opens the docs. Microsoft’s web API guidance makes the same case for clear resource URIs, standard HTTP methods, and response formats that stay predictable as services evolve. (learn.microsoft.com) (github.com) Versioning sits in the checklist because public APIs rarely stay frozen after launch. Google’s design guide and Microsoft’s guidance both treat compatibility as a design problem from day one, with explicit versioning used to ship changes without breaking existing clients. (docs.cloud.google.com) (github.com) Error handling gets equal weight because an API failure is still part of the product. Azure’s best-practices guide recommends standard HTTP status codes and response bodies that explain what went wrong and what the client can do next, instead of returning vague server messages. (learn.microsoft.com) The thread also pointed to the Backend for Frontend pattern, usually shortened to BFF, as a way to avoid one oversized API serving every screen. Microsoft defines BFF as a separate backend layer for each interface, such as web and mobile, so each client gets data shaped for its own limits and release cycle. (learn.microsoft.com) Amazon’s architecture write-up describes the same tradeoff in practical terms: mobile apps often need fewer calls and smaller payloads than desktop clients, while a single shared backend can turn into a deployment bottleneck. In that model, the BFF stays tightly coupled to one user experience and is often maintained by the same team that ships the interface. (aws.amazon.com) The playbook’s emphasis on testing headers and ergonomics early fits a contract-first style of API work. Microsoft’s engineering playbook says teams can write tests against an API definition before business logic is finished, which lets design problems surface in paths, models, and headers before they become production behavior. (microsoft.github.io) That is why a short checklist can travel so far among platform teams. The hard part of API design is rarely exposing one endpoint; it is making hundreds of small decisions feel obvious to outside developers on the first request. (learn.microsoft.com) (google.aip.dev)