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 mistakes, and 5xx for our own failures. I have wasted whole afternoons on APIs that answered every request with a 200 and buried the real outcome in the body, and that habit makes integrations brittle and error handling guesswork. When our status codes are honest and enumerated in the contract, consumers can build retry logic, alerting, and branching that just works. Status codes are a shared language, and I expect every API to speak it correctly.
HTTP Status Codes (OpenAPI)
Strategies
APIs Follow Consistent Design Patterns
All APIs must follow consistent design patterns for naming conventions, media types, pagination, filtering, sorting, and error handling, ensuring that consumers can learn patterns once and apply th...
Experiences
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...
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...
monitoring Monitoring Production
Monitoring is how I keep a promise of reliability. Uptime checks, health endpoints, and alerting tell me an API is doing its job before consumers have to tell me it is not. Monitoring is the differ...
