I wanted to take a moment to once again develop my understanding of why OpenAPI was successful. Some would argue that its success is unevenly distributed because of Swagger-—which is true. I would also say it is also unevenly distributed because of Postman collections, GraphQL, and now with the latest release of AsyncAPI, which enables you to define request/response APIs, this will continue to expand. Even with all of this, it is difficult to argue that OpenAPI is the de facto machine-readable format for defining the surface area of your HTTP APIs.
First and foremost OpenAPI was successful because of Swagger, Swagger Editor, and then ReDoc. It got us on the same page by giving us a common machine-readable way to describe the surface area of an HTTP request/response API that could then be used to generate human-readable. This machine-readable contract gave us a single focal point to define our HTTP APIs in a common vocabulary that aligned teams producing APIs with each other, but then also aligned with consumers, and the wider API community. This alignment is everything. However, this machine-readable artifact could also be used to generate mock servers, SDKs, tests, and other essential elements of API operations.
In 2015 Swagger began the transition to become OpenAPI, and with this change, you could now express OpenAPI as JSON or YAML. While this didn’t live up to the hype that business stakeholders would participate in the API lifecycle, it did make it more readable and accessible, and has significantly widened the conversation. Getting engineers producing APIs on the same page is critical, but getting business stakeholders producing APIs more involved in the life cycle is essential. It is this getting us on the same page that I attribute to why OpenAPI was so successful. It has made APIs more tangible. Something you can see as JSON, YAML, or documentation. Now that we can see it, we can also standardize our APIs across teams, and within an industry. If we aren’t on the same page, we’ll take things to the next level—I don’t care what you say about AI.
I believe OpenAPI would have been 10x as successful if there had been more alignment with the API services and tooling community. Swagger was successful because of tooling, OpenAPI less so. There just wasn’t leadership and alignment coming from the OAI, and whatever momentum we saw was from services and tooling providers taking the lead and offering value to developers, adopting the latest features of the spec, and moving the conversation forward. Sadly, I also saw a lot of startups take advantage of this vacuum and capture, then lock-up value, unwilling to give back to the OAI and the community.
Another significant reason OpenAPI was successful was the adoption and showcasing of the specification by leading public API providers like GitHub, Twitter, Stripe, Twilio, Slack, and others. These narratives stick in the mind of their API consumers, and just the wider API Zeitgeist. This is something further supported by service and tooling providers like ReDoc / ReDocly, APIMATIC, Bump.sh, and others who provide portals, documentation, SDKs, and other services, and then prominently place a button or link to the underlying OpenAPI specification. All of this adds up in the eyes of API producers and consumers, resulting in more adoption of the specification behind the scenes of the enterprise, as well as out in the open via public API portals.
Ultimately OpenAPI was successful because it provided us with a common vocabulary for describing APIs. Yes, this was primarily in tandem with API documentation. But that is just a manifestation of the alignment between API producer and consumer, where the alignment between teams producing API is hidden behind, yet equally as important. I agree with Daniel Kocot, in the Nordic APIs article about him titled, “API Design in the Post-OpenAPI Era”, but feel this is more about design-first vs. code-first dogma and ideology, than it is about OpenAPI. The specification is baked into things, and not going anywhere soon. However, the way we use the specification will continue to shift and evolve in coming years, and I predict we’ll see a resurgence of tooling that moves beyond visions proposed by API management providers, and help us get on the same page at scale while properly dealing with change using the OpenAPI specification.
