Customers / CLOUDFLARE

Just a single pull request is now required to ship an SDK change.”

20-30
API schema updates per day
1,000+
endpoints across three SDKs

Building an automated SDK pipeline with Stainless

“The decision to use Stainless has allowed us to move our focus from building the generation engine to instead building high-quality schemas to describe our services.

In the span of a few months, we have gone from inconsistent, manually maintained SDKs to automatically shipping over 1,000 endpoints across three language SDKs with hands-off updates.”

Jacob Bednarz
API Platform Tech Lead

Cloudflare provides a comprehensive suite of cloud-based services designed to enhance the security, performance, and reliability of websites and web applications. It operates a vast, global network that acts as a protective barrier, guarding against cyber threats like DDoS attacks, while also accelerating content delivery through its advanced Content Delivery Network.

Before adopting Stainless, Cloudflare’s SDKs were manually maintained by dedicated engineers. For every product addition or improvement, they needed to orchestrate a series of manually-created pull requests to get those changes into customers’ hands. This, unfortunately, created an imbalance in the frequency and quality of changes that made it into their SDKs. Even though the product teams would drive some of these changes, not all programming languages were covered by Cloudflare’s engineers — some relied on community-driven contributions or third-party library maintainers.

Following the completion of their transition to OpenAPI from JSON Hyper-Schema, Cloudflare  began exploring other ways that they could take advantage of their OpenAPI specifications besides just generating documentation. It was time to use OpenAPI to generate their SDKs.

CODE GENERATION

“You should not be able to tell what underlying language generated the SDK.”

Cloudflare has a lot of APIs—most of their user-facing functionality is backed by an API somewhere. When Cloudflare introduces new APIs, they have found that user adoption is heavily impacted by SDK support— if a new feature or product never makes it into the language SDK that is driving the user’s API calls, it’s as good as non-existent.

Producing a good SDK is more involved than many developers may realize, especially when relying on code generation. The details matter, and it’s not just about pretty code—it’s about making the right choices and balancing some challenging tradeoffs between the characteristics of REST APIs and the idioms of the language at hand. When launching a new feature, delivering first-class support across every language SDK concurrently is a profound technical challenge.

GENERATION MACHINE

“In the span of a few months, we have gone from inconsistent, manually maintained SDKs to automatically shipping three language SDKs with hands-off updates freely flowing from the internal teams.”

Cloudflare analyzed their situation and saw that if they decided to build the solution entirely themselves, they would be at least 6–9 months away from a single high quality SDK with the potential for additional follow-up work each time they introduced a new language. They explored the OpenAPI generation landscape hoping to find a solution that would reduce the overhead of supporting additional languages.

Due to the size and complexity of their schemas, they weren’t able to use most off-the-shelf products. They tried a handful of solutions and workarounds, but weren’t comfortable with any of the options—until they tried Stainless. Founded by one of the engineers that built what many consider to be the best-in-class API experiences at Stripe, Stainless is dedicated to generating high-quality SDKs.

The way Stainless works is that you bring your OpenAPI schemas and map them to methods with a configuration file. Those inputs then get fed into the generation engine to build your SDKs. This approach makes it possible for Cloudflare to handle SDK updates for the majority of their API changes using the existing schemas, but they still have the flexibility to modify behavior on a per-SDK basis using the configuration file when they encounter SDK-specific issues.

The decision to use Stainless enabled Cloudflare to move their focus from building the generation engine to instead building high-quality schemas that describe their services. In the span of a few months, they went from inconsistent, manually maintained SDKs to automatically shipping three language SDKs with automated updates freely flowing from API changes made by the internal teams. Best of all, it is now a single pull request workflow for the majority of their changes — even if they were to add a new language or integration to the pipeline.

Due to the size and complexity of our schemas, we weren’t able to use most off the shelf products. We tried a handful of solutions and workarounds, but we weren’t comfortable with any of the options; that was, until we tried Stainless.”

Jacob Bednarz
API Platform Tech Lead