A lot of attention is given to a finished and complete OpenAPI for any HTTP API. This is a good thing, but it is also equally important to focus attention on the importance of everything that goes into an OpenAPI, which rises above any individual OpenAPI and contributes to the overall strength and velocity of an enterprise. Today’s OpenAPI artifact is often the result of multiple product, architect, engineering, and platform roles contributing to a single OpenAPI artifact over time, with the following ongoing benefits across teams who are producing APIs inside and outside of the enterprise.
- Education - Individuals who engage with an OpenAPI from design to production will understand OpenAPI, but also HTTP APIs.
- Coordination - Teams producing APIs build up practice working together to produce OpenAPI artifacts for HTTP APIs in layers.
- Asynchronous - Each OpenAPI can iterate over time in asynchronous ways across teams to help make for a more efficient process.
- Consistency - OpenAPI provides the guard rails and check list for teams producing APIs to help achieve a higher level of consistency.
- Observability - Each OpenAPI artifact contributes to the overall observability of API operations as well as the API resources produced.
A complete OpenAPI is the output of all of this. High quality and complete OpenAPIs depend on a well oiled machine across all of these areas. OpenAPI output does not equal downstream success with gateway configuration, documentation, and SDK generation. The OpenAPI is not what matters the most, it is just a machine-readable manifestation of what matters the most. Many people see OpenAPI as simply a configuration for gateway, documentation, SDKs, or governance, when it is all those things, but it is also the thing that hates everyone the same page rowing in the same direction.
