API Advice

Building Speakeasy

OpenAPI SDK Creation: Speakeasy vs Open Source Client Generators

Sagar Batchu

December 6, 2023

Want to understand how Speakeasy compares to the open source client generators project? Here's the short anwer:

• OSS Client Generators are a great option for hobbyists who want to create a simple SDK for their API.

• Speakeasy has been designed for enterprise APIs that face more scrutiny from users and have more complex requirements. Speakeasy is designed to provide a best in class DevEx and full support for your API.

In this article, we'll dive into business and technical considerations and explore the differences in more detail.

If you want a purely technical comparison, check out our breakdowns for each language.

Technical Comparisons

Typescript

Python

Go

Open source generators require eng investment to be enterprise-ready

Open-source software might seem free, but has a lot of hidden costs that any enterprise user should consider carefully:

• Spotty OpenAPI compatibility: you can’t be sure that the OSS generator will support your entire API spec. Your eng team will need to create hacks and workarounds — creating additional pressure on the core product roadmap and hurting eng velocity.
• Non-idiomatic code: your SDKs must be easy for any developer to pick up and use. Javascript SDKs should look and feel different from C# SDKs. Unfortunately, this is often not true for OSS generator, which is created and maintained by hobbyists — many of whom may not be experts in a given language. This undermines the SDK effort from the start.
• Huge number of bugs: 3.9K open issues as of Nov 2023 — and growing ~10% every year.
• Zero support options: your eng team will be on the hook for fixing any issues throughout the initial implementation, and beyond.
• Requires work to automate: you’ll need to design, plan, and implement a system that embeds the OpenAPI generator into an automated SDK maintenance workflow. This is a non-trivial investment.
• Security: OSS generator’s reliance on community contributions means that it can be difficult to know what security practices and dependency update policies are being followed. When issues do occur, resolution times are often opaque.

“OpenAPI gen doesn’t work very well — the code often doesn’t look and feel right, and certain aspects of OpenAPI just aren’t handled well. We would probably still have needed to spend a ton of engineer time working around its limitations and quirks, and we decided that the headache wasn’t worth it.”

Roy Pereira, Unified.to CEO & Co-Founder

In summary: given the limitations above, we believe that OSS generators are best for hobbyists.

For an enterprise that wants to appeal to developers and showcase a compelling API experience, using OSS tools successfully will require a significant investment in engineering resources, and significant time-to-market.

This is likely to require a minimum of 3 FTE engineers, scaling up depending on the number of SDK languages required.

• This engineering effort must be maintained over time: every time APIs in the organization changes and evolves, SDKs and docs must be updated
• Robust product, tech writing, QA and release management teams and processes must also be employed to ensure the SDKs are fit for purpose

TIP

Total cost of ownership for OSS tooling is likely to be 3+ FTEs at a minimum, depending on the API surface area and SDK languages required. This is an ongoing commitment.

OSS usage in an enterprise: a real-world example

Don’t just take our (or our customers’) word for it however. See what the API Architect of a publicly traded company posted (opens in a new tab) in Nov 2022, upon his team’s completion of a project to develop SDKs using OSS tooling. The post is equal parts celebration of the accomplishment and postmortem on the pain suffered.

tl;dr

Using the OpenAPI Generator required a ton of eng investment:

• Creating custom templates to work around the generator's inconsistent OpenAPI support.
• Finding and debugging complex issues in the generator code.
• Creating a custom build process to manage ongoing generation for multiple languages.

Here are just a few key quotes from the post:

Speakeasy offers a better product, at a lower support cost

Speakeasy’s mission is to make it easy to create and consume any API.

Our products have been designed from the ground-up to deliver great Developer Experience for your API — with a focus on the needs of enterprises.

What constitutes a great developer experience is of course subjective, but the core tenants for our SDKs are:

• Full OpenAPI Coverage, We plan to have broad coverage of the OpenAPI specs while having a deep focus on the most common ways of defining an API and ensuring you have a nice to use SDK as the output.
• Fully typed so that SDKs feel like they have been written by a human: easy to read and debug.
• Batteries included where everything from retries to pagination of your APIs is handled as part of the SDK generation (Available in our closed beta).
• Easy to use, our SDK generators are fault tolerant, and designed to always output usable SDKs where possible. If we can't output a usable SDK, we will provide human readable error messaging about why validation of your OpenAPI spec failed (instead of just failing silently or with obscure error messages or giving you a broken SDK)

Here’s how Speakeasy compares to OSS tools:

“Finding Speakeasy has been transformational in terms of our team’s velocity. We’ve been able to progress our roadmap faster than we thought possible. We were able to get SDKs for 3 languages in production in a couple of weeks -- if we’d been on our own, it would probably have taken a month for each language.”

David Coplowe, DevEx Team, Codat

In summary, Speakeasy delivers:

• Significant cost savings: Total Cost of Ownership at a fraction of building on top of the OSS tools.
• Proven high-quality Developer Experience for your API: used by companies like yours every day to appeal to developers and grow API usage.
• Faster time-to-market: get up and running in a week or less.