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 not smuggle state changes into a GET or overload a single verb to do everything. I have debugged too many APIs where a POST quietly deleted data or a GET had side effects, and that ambiguity breaks caching, retries, and every consumer's mental model. When our methods mean what the web says they mean, tooling and developers can reason about our API without reading the source code. This is the most basic contract we make with the protocol, and it is worth getting right.
HTTP Methods (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...
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...
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...
