TNS
VOXPOP
Do You Resent AI?
If you’re a developer, do you resent generative AI’s ability to write code?
Yes, because I spent a lot of time learning how to code.
0%
Yes, because I fear that employers will replace me and/or my peers with it.
0%
Yes, because too much investment is going to AI at the expense of other needs.
0%
No, because it makes too many programming mistakes.
0%
No, because it can’t replace what I do.
0%
No, because it is a tool that will help me be more productive.
0%
No, I am a highly evolved being and resent nothing.
0%
I don’t think much about AI.
0%
API Management / Software Development / TypeScript

In a TypeScript World, Code Generation Is Key for API SDKs

We speak to Stainless about why codegen is critical for modern API management, how it worked with OpenAI, and which API format is best.
May 8th, 2024 4:00am by
Featued image for: In a TypeScript World, Code Generation Is Key for API SDKs
Image via Stainless website. 

It’s a measure of how complex the API ecosystem has become that companies like Stainless, an SDK generator for APIs, even exist.

Founder Alex Rattray previously worked on the developer platform team at Stripe, and I spoke to him recently about why code generation (codegen) is critical for today’s APIs, the work Stainless has done with OpenAI, and the state of APIs in 2024.

While at Stripe, Rattray had created a code generation system that would generate an SDK for an API automatically. These types of systems had “basically been handwritten before,” Rattray told me, and so he became known within Stripe as “the SDK person.” He soon realized that building an SDK system for API management is a market opportunity in the developer tools space.

“Basically, everybody with an API wants an SDK if they care at all about the developer experience,” he said. “But building it yourself is a ton of work — it’s prohibitively expensive to do a good job of this. Sometimes people think it’s easy and you can just pull it out; and then it turns into this terrible maintenance burden.”

A Hard Problem… Because of Static Typing

The API ecosystem on the web is now decades old, so I asked Rattray why it has taken so long for a market to open up for API SDKs.

“It’s just a surprisingly hard problem,” he replied, adding that the open source solutions available are “more work than you would think.”

API SDKs are a hard problem due to the rise of TypeScript over the past five years.

The reason why it’s a hard problem is due to the rise of TypeScript over the past five years — “and other statically typed languages,” he added, noting that this now included the likes of Python and Ruby (both traditionally dynamically typed). The rise of statically typed languages, like TypeScript but also Go and Kotlin, made creating an SDK for an API system much more complicated than it had previously been.

“With static typing, you have to specify every single request parameter and response field. So the order of magnitude of things that you have to do for your API goes from tens to […] 150 endpoints. And, like, a large engineering team can manage a 150-endpoint API SDK, but you’re looking at thousands to tens of thousands of request parameters and response fields. And every single character has to be correct, right? Like if you get anything a little bit wrong, that thing is broken.”

“The developer now just expects everything that they do to be fully typed,” he added, “and so if you’re interacting with an API and you don’t have types for it, you feel like you’re grasping around in the dark.”

‘You Absolutely Need Codegen’

If static typing is now a requirement to work with APIs, then “you absolutely need codegen,” said Rattray. As a recent Stainless blog post put it, “building SDKs that support comprehensive static types in a variety of languages was totally unthinkable without code generation.”

“Our code is a little bit like using React, when we’re crafting a new SDK on the codegen side.”
– Alex Rattray, Stainless CEO

Codegen happens to play right into Rattray’s strengths. The Stainless website states that Rattray “created Stripe’s patent-pending client library codegen system.” This type of system is at the center of what Stainless offers.

Rattray said that the Stainless codegen system is inspired by compiler technology, but also — perhaps surprisingly — by React.

“So code-generation, I think of it as sort of like this niche, almost forgotten, corner of computer science, that sort of sits adjacent to compilers,” he said. “But it’s a little bit different. So when we build our code-generation system, we draw a lot of inspiration from compilers and compiler theory, but we also draw inspiration from renderers and the UIs. So our code is actually a little bit like using React, when we’re crafting a new SDK on the codegen side.”

Using AI and Working With OpenAI

Stainless has worked with both OpenAI and Anthropic so far; and in fact the product uses a bit of AI magic itself.

“So the primary way that we use generative AI to improve our product is, when someone signs up for Stainless we generate, with AI, a sort of a first guess at what they’re Stainless config looks like.”

He explained that a Stainless config is what maps a customer’s API to their SDK — “so this endpoint should have this method name, and the libraries.”

Stainless in action

Stainless in action.

He was quick to point out, though, that the human API designer must make the final decisions.

“And so that’s one of those things where we use some heuristics and we use a lot of AI to craft this first version, but it’s all up to the API designer to make everything perfect.”

The partnership with OpenAI, however, came before generative AI was added to the Stainless product. Stainless worked with OpenAI on its TypeScript/Node SDK for the OpenAI API, which was released last August. That relationship began through the “Stripe mafia,” with an ex-Stripe employee who now worked for OpenAI approaching Rattray.

“When he joined the [OpenAI] API team, he saw that they had challenges with their SDKs — they were having a hard time devoting the resources it would take to have the developer experience that they wanted. And so he suggested that we get in touch; and by that time, we were actually already working with Anthropic and supporting their client libraries through the exact same process essentially.”

The API Ecosystem

When I spoke to API expert John Musser a few years ago about the API ecosystem, he pointed out there is much more diversity in API formats nowadays. While REST (Representational State Transfer) is still by far the leading format for offering APIs, other formats such as GraphQL, gRPC, WebSocket and webhooks were all rising in popularity.

Stainless wants to fix the problems of REST, particularly in the world of statically typed languages.

That API diversity is still prevalent today, but Rattray told me that his company is purely based around REST because it is still the biggest API format. However, what Stainless wants to do is fix the problems of REST, particularly in this world of statically typed languages.

“People have had a lot of problems and struggles with REST. I mean, fundamentally, if you don’t use an SDK generator like Stainless — and Stainless has not existed until today — [then] you don’t have proper static types when you consume the API’s. And that’s a really huge issue, especially for people using languages like Go and Java — but also, again, at this point really any developer ”

While Rattray recognizes the strengths of other formats, he thinks companies ought not to “mix and match” their APIs.

“This fractured nature of the ecosystem also poses a lot of problems,” he explained. “If you’re an engineering leader, […] you’re going to end up too often in situations where you have your GraphQL API for the frontend, gRPC APIs for your microservices, [and] you have a REST API for your public API.”

Rattray says that the vision for Stainless is “to make REST basically as good as GraphQL or as gRPC — have all the advantages that they have, so that teams can just use one simple technology everywhere.”

Group Created with Sketch.
TNS DAILY NEWSLETTER Receive a free roundup of the most recent TNS articles in your inbox each day.