Require that consistent, cross-cutting changes to OpenAPI definitions be applied through OpenAPI Overlays rather than by hand-editing each specification. I want shared conventions, added examples, governance annotations, and audience-specific variants expressed as overlays that layer cleanly over a source definition. This keeps the canonical spec authoritative while letting teams reuse a single set of adjustments across many APIs without drift. Copy-and-paste edits are how standards decay; overlays are how we keep definitions consistent and reusable, so I hold their use as a design-time expectation.
OpenAPI Overlays Used
Rules
APIs.json Overlay Info
APIs should declare an OpenAPI Overlay so consumers can discover documented, reusable modifications applied to the API's OpenAPI definition. Declaring a property of type OpenAPIOverlay in the APIs....
Strategies
APIs Provide Orchestration Workflows
I want our APIs to ship the workflows, not just the endpoints, because most real jobs take more than a single call and I would rather hand consumers a proven path than make them assemble one from s...
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...
Reusability
Reusability is the experience of finding and applying an existing API instead of building the same capability again. It depends on discovery, consistent design, and clear documentation that make an...
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...
