Product Updates
Evolving enums for evolving APIs
Georges Haidar
May 15, 2024 - 4 min read
Today we’re announcing support for “open” enums in our Go, Python and TypeScript code generators. This feature will help you ship SDKs that continue to work as you evolve your API and without causing your users unnecessary dependency management churn.
What even is that?
An enum is considered “closed” when it specifies a strict set of members like this TypeScript enum:
Other languages, like Python and Java, treat enums similarly by default for example.
An “open” enum, on the other hand, is one where unrecognized values can be expressed alongside the known members. Some languages may not have a way to make enums open but we can find a way such as with branded types in TypeScript:
We’ll continue using TypeScript as the target language for the rest of this post.
The problem
Enums in OpenAPI and JSONSchema have presented developers with a unique challenge when it comes to making updates to their API. Let’s consider an example where we have an API to fetch a blog post from a CMS:
If we’re building a TypeScript SDK with Zod for runtime validation from
this API description, the code for the BlogPost schema might look like this:
We’re showing an example here with TypeScript enums but the problem we’re
solving is also present when using literal string unions like if we were to
define Category as:
The Speakeasy TypeScript SDK generator lets you choose if you want to generate TypeScript-native enums or literal unions.
We ship version 1 of our SDK and users can interact with the API like so:
Some time passes and we’ve decide to add a new “tech” category to our API. We update our API description as follows:
Once we deploy this change to our servers, users on v1 start getting validation
errors because the category tech is not recognised by the SDK.
This is not a novel problem and depending on the language and API description format you’re using, enums are sometimes treated as “closed” by default which gives rise to this challenge with evolving APIs.
There is a longstanding GitHub issue in the OpenAPI community to address this problem. In a different world, protobuf enums have varied representations where certain languages translate them to open enums and others to closed.
How we’re solving it
Previously, the Speakeasy generator treated enums as closed and emitted code
appropriately in target languages. Starting from today, we’re exposing an
OpenAPI extension, x-speakeasy-unknown-values, to allow you to selectively
mark certain enums in your API description as open.
To get started, add the extension to your enums:
SDKs generated after this change will now have a Category enum type that is
open. For TypeScript, the code we generate is equivalent to the following
snippet:
In case you’re interested, here’s how catchUnrecognizedEnum works to create a
branded type:
Speakeasy TypeScript SDKs explicitly emit TypeScript types that are tied to Zod schemas instead of being inferred from them.
Continuing with our example above, when the new “tech” category is introduced, the following code continues to compile and work:
Users of the SDK also get the editor support they’re used to when working with enums. For instance, switch-blocks work great for branch logic over enums:
Great! It seems we’ve done a lot of work to get back to client code that continues work. The net outcome, however, is that we’ve made more room for our APIs to evolve without causing issues for users on older versions of our SDK. This is in addition to retaining good type safety, backed by strict runtime validation, and great developer experience (editor auto-complete continues to work for open enums).
Wrapping up
The “open” enums feature, using the x-speakeasy-unknown-values extension, is
available for Go, Python and TypeScript SDKs with support for additional
language targets being added in the future. Check out our docs on customizing
enums to learn about this and other customization options.