Building Speakeasy

OpenAPI has flaws, so what?

Sagar Batchu

February 11, 2025

When we started Speakeasy, we considered creating a DSL (domain-specific language). Our goal was to autogenerate SDKs from our user’s API configuration files. Creating a DSL would’ve allowed us to design the exact SDK configurations available to our users.

However, we decided against it. Instead, we opted for the preexisting OpenAPI standard (opens in a new tab), which is indisputably the most popular standard for defining REST APIs. A typical OpenAPI spec details the API routes, inputs, and expected outputs. They are either handwritten or (increasingly) autogenerated by popular API frameworks such as FastAPI (opens in a new tab).

Years later, we are confident that we made the right choice. Using OpenAPI admittedly created some complexity for us — and we are stuck with the verbosity of the spec — but we also believe that our product wouldn’t be where it is today had we built a DSL.

Today, I want to share our learnings in hopes that it will encourage developers to use existing standards as a default choice instead of creating their own (provided that workarounds exist to avoid future limitations).

Why we considered a DSL

The benefit of creating a DSL is that we could start with a clean slate. We could strictly focus on what matters to our generated SDKs; we wouldn’t have to navigate all the cruft and endless permutations of a preexisting spec.

Another advantage is that DSLs (when done well) are a design-first strategy that actually gets used. While OpenAPI can also theoretically be used as a design-first language, its verbosity means it’s more often autogenerated by an API framework. Accordingly, developers aren’t forced to sit down and think through their SDK’s design as a DSL user would have to.

Ultimately, we believe these benefits of opting for a DSL are overwhelmingly mitigated by the advantages of using a widely adopted spec. Let me explain why.

The flagship advantage of a preexisting standard

The flagship argument of using a widely accepted standard is that it creates the best long-term developer experience. Developers are either already familiar with the spec or can benefit from tools that autogenerate it. In the case of OpenAPI, it’s primarily the latter.

The ubiquity of OpenAPI creates other benefits. OpenAPI has a huge community, meaning errors and quirks are well-documented and easy to learn. Additionally, the spec doesn’t exist in a vacuum — it’s part of a larger ecosystem. For example, OpenAPI users can tap into Arazzo (opens in a new tab), OpenAPI’s workflow and a tooling ecosystem that can provide docs, testing, and more.

A DSL doesn’t technically eliminate the OpenAPI spec; it just exists in parallel to it. However, it still chips at the benefits of a universal spec because it distracts developer focus from one unified source of truth.

The beauty of vendor extensions

The main limitation of OpenAPI is that it doesn’t support every desired feature, especially features pertinent to building scale-friendly SDKs. Thankfully, OpenAPI was designed with a built-in strategy for handling these deficits: vendor extensions.

Vendor extensions (opens in a new tab) are an OpenAPI feature that enables companies building on the spec (such as Speakeasy) to expand it. A vendor extension involves adding additional fields to the OpenAPI spec, enabling end users to expand their OpenAPI spec’s coverage.

Speakeasy’s vendor extensions are what makes Speakeasy possible. Without them, we’d have to defer to a DSL (despite the issues) to accommodate missing OpenAPI features such as pagination, streaming, and retry automation. With vendor extensions, we get the best of both worlds; it negates the myth that DSLs produce better code. In fact, vendor extensions can enable the best code generation. We put our energy into building a great OpenAPI linter that can encourage the best practices — bandwidth that would otherwise be spent on creating a new spec from the ground up.

The curious case of vendor lock-in

Another common argument for universal standards is that they don’t subject users to vendor lock-in. However, I hesitate to grandstand on this. Yes, OpenAPI minimizes technical debt should a customer want to switch providers. But it also doesn’t exactly eliminate lock-in.

One of the main reasons that customers opt for solutions like Speakeasy over OpenAPI’s built-in SDK generator (opens in a new tab) is due to improved code quality and coverage—made possible by Speakeasy’s vendor extension. Accordingly, we still subject our users to some vendor lock-in. We also enforce some opinionated (and popular) conventions, such as mandating Zod (opens in a new tab) for schema validation and oneOf structs over anyOf structs. These design standards aren’t specific to Speakeasy but do encourage users to stay, as they’re compatible with our flavor of SDK generation.

However, in our defense, the goal of vendor extensions is strictly to patch coverage. Our value proposition is providing top-tier SDK generation; a comprehensive vendor extension is just a byproduct of that mission. Our dream outcome would be for OpenAPI to integrate concepts from our vendor extension into their spec, with our users gradually migrating to the unified standard. And this isn’t a pipe dream — we’ve been able to make real suggestions to the OpenAPI technical steering committee by referencing how we address gaps in the spec with our opinionated choices (such as this example re. server-side events (opens in a new tab)).

A closing thought

I want to close on my general worldview of existing standards/specs: If the standard gets you 70% there, it’s better to fill in the gaps and nudge the community’s developers in the right direction. Otherwise, creating a brand-new “all-encompassing” spec runs into the problem in this xkcd strip:

Developer experience of the tooling you sell matters, but your tool doesn’t exist in a vacuum. We don’t want to hurt the long-form developer experience because of a prideful notion that we could create a better experience than OpenAPI. End of day, OpenAPI is and will remain the most popular standard because it’s supported across tools. It’s better for us to leverage OpenAPI’s foundation, play nice with the existing ecosystem, and unlock new features through OpenAPI’s extensibility features that exist for a reason!