API Design

An API is a contract. Breaking it breaks callers. Design for evolvability from day one.

Contract-First

Design the interface before the implementation. Write the schema or proto before any code.

Contracts force clarity on resource modeling, field names, and error cases early.
If the design is painful to describe, the implementation will be painful to use.
API review at design time is cheap; API review after clients exist is very expensive.

Every breaking change requires a new version. Communicate it, window it, enforce the schedule.

Breaking: removing a field, changing a field type, changing semantics of a status code, renaming a resource.
Additive (non-breaking): new optional fields, new endpoints, new enum values in response.
URL-path versioning (/v1/orders) — visible, cacheable, easy to route; good for major versions.
Header versioning (API-Version: 2024-01-01) — cleaner URLs; common for date-based schemes.
Set a deprecation window (minimum 6 months for external APIs) and enforce it; sunset headers signal the date.