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 API easy to understand and safe to depend on. The more reusable an API is, the more leverage every team gets from the work that went into building it. I champion reusability because rebuilding the same capability over and over is one of the biggest sources of waste in technology. When APIs are discoverable, well-designed, and trustworthy, teams reach for them by default rather than reinventing them. Reusability is where good API practices turn directly into saved time and money.
Reusability
Policies
Arazzo Workflows Provided
Require that APIs which chain multiple operations to accomplish real work provide Arazzo workflow definitions describing those sequences. I want the multi-step paths a consumer must follow, the ord...
Schema Registry (CI/CD)
Require that the schemas an API relies on are published to a shared schema registry and validated against it in CI/CD, so the shapes of our data are versioned, discoverable, and compatible. I want ...
Open Source Tooling Preferred
Require that an API operation prefers open source tooling and applies open licensing to its definitions, SDKs, and supporting tools wherever practical. Open source lets consumers understand, extend...
OpenAPI Overlays Used
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, ...
Reuse Scoring Applied
Require that every API carry a reuse score that measures how widely and effectively it is being reused across teams and how much it duplicates existing capabilities. I want reuse assessed with a co...
Strategies
API Parameters Are Well-Defined and Consistent
All API parameters must have clear names, descriptions, types, and constraints following consistent casing and naming conventions, with reusable parameters centralized in OpenAPI components to redu...
APIs Are Discoverable Through a Central Catalog
All APIs must be registered in a central catalog or registry with consistent metadata, tags, and descriptions, ensuring that producers and consumers can find existing APIs before building new ones,...
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...
