API design

Design the contract from the consumer's side, write it down in a machine-checkable form, and make every change's compatibility explicit. Implementation follows the contract, not the reverse.

Phase 1: Know the consumers

• Identify each consumer (browser, mobile client, partner, internal service, library user), how they deploy, and how long old clients stay in the wild. That sets the compatibility budget.
• Read existing APIs, style guides, schemas and generated clients in the repository. Follow the house conventions for naming, casing, pagination, errors and auth even where you would choose differently.
• Write two or three real consumer calls first: the request, the response they need, and what they do on failure.

Phase 2: Shape the contract