Contracts and security
Describe the API with OpenAPI
Write a machine-readable contract for routes, parameters, request bodies, responses, and reusable schemas.
8 minute lesson
OpenAPI describes an HTTP API independently of one client or server implementation. It supports documentation, validation, client generation, and review.
Start with the paths and schemas the API already implements. Name every response status and media type. Keep the document in version control and test it against behavior so it does not become an attractive but false contract.
Describe the wire format, not TypeScript implementation types. Mark required properties, distinguish nullable values from missing properties, specify parameter locations, and reuse schemas without hiding meaningful differences between create input and a stored Book. Examples help readers but do not constrain a value unless the schema does.
Pin the OpenAPI version declared by the document and validate it with a current parser in CI. Contract tests should exercise representative success and known error responses, including headers such as Location and the problem-details media type. Review generated clients as consumers: a surprising optional field or undocumented status is evidence that the description and server have drifted.
Describe GET and POST /books, including the Book schema, create input, 200, 201, 422, and problem responses.
Lesson completed