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 have written integrations against APIs whose success responses were a shrug, and every field became a discovery exercise in production. A concrete response schema lets consumers generate models, validate payloads, and trust the structure they are coding against, and it lets our own tests catch drift before it reaches anyone. If we cannot describe what success looks like, we do not really understand our own API yet.
2xx Response Schema (OpenAPI)
Strategies
API Responses Must Be Meaningful and Consistent
All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers...
Experiences
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...
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...
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...
