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 proxy or load balancer happened to emit. I have watched a 500 return raw HTML from some middlebox while the rest of the API spoke clean JSON, and that inconsistency shows up at the worst possible moment for the consumer. When our server errors use a declared media type, client error handling stays uniform across success and catastrophic failure alike. The failure case is exactly when consistency matters most, and I want it defined in the contract.
5xx Response Media Types (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
Interoperability
Interoperability is the experience of APIs, systems, and data working together without heroic effort. It is built on shared standards, common schema, and predictable contracts that let one system t...
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...
Reliability
If an API isn’t reliable, consumers will eventually look for alternatives. Reliability starts with the platform and infrastructure where the API is deployed, but it also depends heavily on the pace...
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...
