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.
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:
“To ensure we would be able to run the code-generation process within our Continuous Integration (CI) pipeline, we needed to use a Dockerised version of openapi-generator-cli (the coordination of which was a complex process).”
“Another challenge we encountered was the quality of the community-driven language templates. They worked but templates didn’t appear to be well maintained over time, nor did every feature in our OpenAPI specification have a corresponding implementation in the language templates.”
“Language templates didn’t support the latest programming language version, and the generated documentation wasn’t as good as we needed it to be.”
“Our OpenAPI specification files would cause problems in the generator… Each of these issues would result in hard-to-debug compilation errors within the code-generation pipeline, and so we would have to figure out which of the three potential layers the issue was stemming from: 1. The Fastly OpenAPI specification documents. 2. The openapi-generator mustache templates (opens in a new tab). 3. The openapi-generator language parsers (opens in a new tab) (written in Java).”
“We had to iterate on both ends of the integration, a bit like trying to fit a square peg into a round hole, then gradually changing the shape of both the peg and the hole until they fit.”
“Auto-generating our API clients has been a long project… The code generation itself hasn’t been easy: we’ve had to balance the complexity of coordinating changes across multiple repositories while handling errors over multiple layers, and producing API clients that are not only idiomatic to the language they’re built in but also correct and accessible.”
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:
| Feature | Speakeasy | OSS |
|---|---|---|
| CI/CD integration with 5 minute quickstart | ✅ | ❌ |
| Full OpenAPI3.1 support | ✅ | ❌ |
| Idiomatic code | ✅ | ❌ |
| Customisable SDKs with optional features like streaming support and retries | ✅ | ❌ |
| Automated major and minor versioning | ✅ | ❌ |
| Automated publishing to package managers | ✅ | ❌ |
| Every SDK compilation tested | ✅ | ❌ |
| API & SDK documentation included | ✅ | ❌ |
| Enterprise support and SLAs | ✅ | ❌ |
“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.
