Name the contract surface
An API contract is more than OpenAPI. It includes status codes, pagination, auth behavior, idempotency, error shapes, rate limits, and lifecycle rules.
Compatibility is a product promise
Consumers do not care that a field was convenient to rename. They care whether their integration keeps working. Make breaking change policy explicit.
{
"error": "validation_failed",
"traceId": "00-...",
"fields": {
"email": ["must be a valid email address"]
}
}Keep a small test matrix
| Area | Contract check |
|---|---|
| Error shape | Snapshot sample responses |
| Pagination | Empty, first, middle, last page |
| Idempotency | Retry creates one effect |