3. API-first and contract-driven development
Date: 2026-05-03
Status
Accepted
Context
Internal and external consumers need predictable interfaces. Ad-hoc endpoints and undocumented payloads slow integration and increase defects—especially when multiple contributors and AI assistants touch the same surface area.
Decision
Design APIs first where feasible: define contracts using OpenAPI, gRPC .proto files, GraphQL schemas, or equivalent, before or alongside implementation. Changes flow from the contract; breaking changes require explicit review.
Consequences
- Positive: Assistants and engineers share a single source of truth for request/response shapes.
- Positive: Enables contract tests and generated clients where we choose to adopt them.
- Tradeoff: Upfront schema work for small endpoints; we keep schemas proportional to API importance.