Every API is a contract, and the contract experience is about how clearly the promises between provider and consumer are expressed. Technical contracts like OpenAPI and AsyncAPI describe what the API does, while business contracts like terms of service and SLAs describe the relationship around it. The clearer these contracts are, the more confidently people can build on an API. I have watched countless integrations succeed or fail based on how honest and complete the contracts behind them were. When contracts are explicit, versioned, and validated, consumers know exactly what they are getting and providers know exactly what they have promised. When contracts are vague or undocumented, every integration becomes a negotiation, and trust erodes quickly.
Contracts
Policies
AsyncAPI Contracts Provided
I require that any event-driven or messaging interface is described with an AsyncAPI document, the same way we insist on OpenAPI for request-response APIs, so that channels, messages, and payloads ...
API Mocking (CI/CD)
Require that every API can be mocked directly from its contract so consumers and downstream teams can build against it before the implementation is finished. I lean on mocking because it is what ma...
Contract Testing (CI/CD)
Require that every API is tested against its own contract in the CI/CD pipeline so the running service can never quietly drift from the OpenAPI it publishes. I insist on contract testing because a ...
Schema Registry (CI/CD)
Require that the schemas an API relies on are published to a shared schema registry and validated against it in CI/CD, so the shapes of our data are versioned, discoverable, and compatible. I want ...
API First (Design)
Require that every API begins with a design-first contract, an OpenAPI definition authored and agreed upon before a single line of implementation code is written. I have watched too many teams code...
Async Webhooks (Design)
Require that any API delivering events to consumers describes its webhooks as first-class citizens in the contract, using the OpenAPI webhooks object to define the payloads, headers, and callbacks ...
Batch Operations (Design)
Require that APIs handling high volumes of records offer explicit batch operations rather than forcing consumers to hammer single-resource endpoints in a loop. Every API must define clear semantics...
Media Types (Design)
Require that every request and response declares an accurate, standard media type, and that content negotiation is handled deliberately rather than assumed to always be JSON. Every API must be expl...
Validation (Design)
Require that every API defines and enforces validation rules in its contract, using schemas, constraints, required fields, and formats so that bad input is rejected with a clear, consistent error i...
HTTP Methods (OpenAPI)
Require that every operation in an OpenAPI definition uses the correct HTTP method for the action it performs, GET to read, POST to create, PUT and PATCH to update, DELETE to remove, and that we do...
HTTP Status Codes (OpenAPI)
Require that every operation documents the HTTP status codes it can actually return, using the standard families the way the web intends, 2xx for success, 3xx for redirection, 4xx for consumer mist...
Operation ID Conventions (OpenAPI)
Require that every operation in our OpenAPI definitions carries a unique, human-readable operationId that follows a consistent naming convention across the whole surface, something like getUser or ...
2xx Response Examples (OpenAPI)
Require that every successful 2xx response in our OpenAPI definitions includes at least one realistic example, so a consumer can see exactly what a good answer looks like without making a live call...
2xx Response Media Types (OpenAPI)
Require that every 2xx response declares the media types it returns, spelling out application/json or whatever content it actually serves rather than leaving the content negotiation a mystery. I ha...
2xx Response Schema (OpenAPI)
Require that every 2xx response defines a schema for its body, describing the exact shape, properties, and types a consumer will receive on success rather than handing back an undocumented blob. I ...
4xx Response Examples (OpenAPI)
Require that our 4xx client-error responses carry real examples, so a developer can see exactly what a validation failure, an unauthorized call, or a missing resource actually returns. I have spent...
4xx Response Media Types (OpenAPI)
Require that every 4xx client-error response declares its media type, so consumers know whether an error comes back as application/json, application/problem+json, or something else entirely. I have...
4xx Response Schema (OpenAPI)
Require that our 4xx client-error responses define a schema, ideally a consistent error object with a code, a message, and enough detail for a consumer to understand what went wrong and how to fix ...
5xx Response Media Types (OpenAPI)
Require that every 5xx server-error response declares its media type, so that even when our own infrastructure fails, consumers still receive a predictable, parseable body instead of whatever a pro...
5xx Response Schema (OpenAPI)
Require that our 5xx server-error responses define a schema, reusing the same standardized error object we use elsewhere so a consumer can handle our failures the same way they handle everything el...
Path Trailing Slashes (OpenAPI)
Require that our OpenAPI paths follow one consistent rule about trailing slashes, and I strongly prefer no trailing slash so that /orders and /orders/ never become two subtly different things. I ha...
Schema Constraints (OpenAPI)
Require that our schemas express real constraints on their properties, the minLength and maxLength, minimum and maximum, patterns, and formats that describe what valid data actually is rather than ...
Schema Property Enums (OpenAPI)
Require that any property with a fixed set of allowed values declares those values as an enum in the schema, so status, type, and category fields cannot drift into a free-for-all of typos and inven...
Schema Property Required (OpenAPI)
Require that our schemas explicitly list which properties are required, so consumers know which fields they can always count on and which ones may be absent. I have written code that trusted a fiel...
Schema Required (OpenAPI)
Require that every request and response body in our OpenAPI definitions references a defined schema rather than accepting or returning free-form, untyped content. I have run into operations that de...
Servers (OpenAPI)
Require that every OpenAPI definition declares its servers, the concrete base URLs where the API actually lives, ideally with an entry for each environment so production and sandbox are both discov...
Strategies
APIs are Defined as API Contracts
All APIs are defined as API contracts so that we can align both the business and technology of delivering consistent high quality APIs, employing source control to manage the technical, but also th...
