APIs provide the cement that binds us to our digital lives. They're the quiet heroes working behind the scenes when we check our fitness stats, order takeout, or send that important work document to a colleague. For those of us building these connective tissues, choosing the right tools to describe and document our APIs isn't just a technical decision—it's strategic.
Let's rewind to a simpler time when API description formats were emerging as a way to solve a fundamental problem: how do we describe APIs in a way that machines and humans can understand? Three formats rose to prominence, each with their own devoted following:
Each format had its strengths. Each had its tribe. Each had its walled garden of tools. And therein lies the problem. 🤔
Let's be honest with ourselves. When we first adopted Swagger, RAML, or API Blueprint, the decision probably felt great. The tooling was slick, the workflows were streamlined, and our productivity soared. We weren't thinking about switching costs—we were solving immediate problems.
One of an architect's key objectives is to create options. But in our eagerness to solve immediate problems, we often trade long-term flexibility for short-term gains.
This is where Gregor Hohpe's brilliant vendor lock-in chart comes into play. Looking at the upper right quadrant labeled "Accepted Lock-in," we see exactly where these API description formats positioned themselves initially: high unique utility with correspondingly high switching costs.
https://martinfowler.com/articles/oss-lockin.html
While we generally prefer less lock-in, this trade-off may well be acceptable at first. We knowingly lock ourselves in, making a conscious decision based on the immediate benefits we're getting.
The vendors knew what they were doing. They created tremendous value through tooling ecosystems: documentation generators, mock servers, client SDK generators, and testing frameworks—all working beautifully within their ecosystem, but not playing nice with others.
As the API economy matured, something interesting happened. The unique value propositions of these competing formats began to diminish, while their switching costs remained high. They were drifting dangerously toward the "Caution" zone in Hohpe's chart—the least favorable box that locks you in but doesn't give you a lot of unique utility.
Developers started to feel the pain. If you built your API program around RAML but needed tools only available in the Swagger ecosystem, you faced a difficult choice: maintain parallel descriptions or undertake a risky migration.
The industry recognized this dilemma, and in 2015, SmartBear donated the Swagger specification to the newly formed OpenAPI Initiative under the Linux Foundation. Swagger 2.0 became OpenAPI Specification 2.0, and a new chapter began.