Require that every operation in our OpenAPI definitions carries a unique, human-readable operationId that follows a consistent naming convention across the whole surface, something like getUser or listOrders rather than an autogenerated blob. I have generated SDKs and client code from specs with missing or clashing operation IDs, and the result is method names no developer would ever want to call. Because code generators, mock servers, and documentation tools all lean on the operationId, a clean and predictable convention pays off everywhere downstream. This is a small discipline at design time that saves everyone real friction later.
Operation ID Conventions (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...
Developer Experience
Developer experience is the sum of every interaction a developer has with an API, from the first time they land on the portal to the hundredth time they call an endpoint in production. It covers do...
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...
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...
