API contracts are team interfaces too
Treating API contracts as shared product language makes integrations easier to build, review and operate.

An API contract is usually introduced as a machine agreement: paths, payloads, status codes. It is also a team interface. It tells designers which states exist, helps client developers distinguish recovery from failure, and gives operators clues about what should be observable.
Model decisions, not storage
Database rows are convenient to serialize and expensive to support forever. Begin with what a caller needs to know. Names should follow the domain rather than the current table layout, and optional values should have an explicit reason.
type CreateTripResult =
| { status: 'ready'; tripId: string }
| { status: 'needs-review'; issues: ReviewIssue[] };
Make failure useful
Validation errors should identify a field or operation and use stable codes. Conflict responses should say which fact changed. Retryable infrastructure failures should be distinguishable from a rejected request. None of this requires exposing internal details.
Keep examples beside the schema
A technically valid schema can still be ambiguous. Examples show ordinary values, boundaries, empty collections, and error shapes. Run them in tests so documentation does not quietly become fiction.
The strongest contracts reduce private interpretation. A new teammate can read the shape, understand the product transition, and know what to do when it does not complete.
The strongest contracts reduce the amount of private interpretation between teams.
A useful note should change the next decision.