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 declared a body but never described it, and a schema-less payload is just a promise to argue about the shape later. Anchoring each body to a named, reusable schema means our data is described in one place, validated everywhere, and safe to generate code and mocks against. If we are moving data in or out of an API, I expect a schema to govern it, because undefined data is undefended data.
Schema Required (OpenAPI)
Strategies
Data Should Be Well-Defined and Validated
The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what t...
Experiences
Quality
The quality of HTTP APIs powering an enterprise tends to decline as the number of ungoverned APIs grows across internal, partner, and public landscapes. Low-quality APIs lead to poor downstream exp...
Contracts
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 A...
Consistency
Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as var...
Lifecycle
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
