API Contracts & OpenAPI

An API contract is only real if something enforces it. Documentation drifts; a specification that generates and validates does not.

OpenAPI describes an HTTP API in a machine-readable document: paths, operations, parameters, request and response schemas, auth. Once that exists you get client SDKs, server stubs, mock servers, request validation, and documentation from a single source.

Spec-first versus code-first. Writing the spec before the implementation forces the interface to be designed rather than to emerge from whatever the handler happened to return, and it lets consumers build against a mock immediately. Generating the spec from code annotations is lower friction and tends to document what you built rather than what you agreed. Both work; the failure mode is having the spec in neither place and calling a wiki page the contract.

Validate at the boundary. If requests are checked against the schema at the edge, a whole category of defensive code disappears from your handlers, and rejections are consistent and explainable. The same schema drives your types, so drift between what you validate and what you assume becomes impossible.

Contract testing catches the thing integration tests usually miss: a provider changing a response in a way that breaks a consumer nobody remembered. Each consumer records what it depends on, and the provider's build fails when it violates any of those expectations. It is how you get confidence without spinning up every service together.

Backwards compatibility is a property of the schema. Adding an optional field or a new endpoint is safe. Removing a field, renaming one, narrowing a type, or making an optional parameter required are all breaking, however small the diff looks. If the spec is machine-readable, a diff tool can tell you which of those you just did.