Card 10/ 10
Recap: Request and Response Contracts
Every field's name, type, format and meaning when missing is written down once, where machines can check it.
A contract is what lets two teams build apart and still fit.
- A contract specifies paths, methods, fields, types, formats, errors and authentication, never the database.
- Content-Type names the body's format, Accept the format wanted; 415 and 406 answer mismatches.
- Conventions: one naming case, ISO 8601 dates with an offset, money in minor units with a currency, ids as strings.
- Absent, null and empty mean different things, and the contract says which each field uses.
- Lists are objects with items and a cursor or next link.
- OpenAPI makes the contract machine readable, for validation, clients and documentation.
- Contract-first suits several teams; code-first suits one.
- A database row is not a response type.
| Decision | Convention |
|---|---|
| Field names | camelCase, no abbreviations |
| Dates and times | RFC 3339, with an offset or Z |
| Money | An integer in minor units, with an ISO 4217 code |
| Identifiers | Strings |
| No value | null, with the field present |
| Lists | An object with items and a cursor |
| Where it is written | An OpenAPI document |
← → move through sections and cards