API Change Detection & Open Enums

New features to the Speakeasy Platform - May 29, 2024

Two exciting new features are coming to Speakeasy this week: API Change Detection and Open Enum support.

Let’s get into it 👇

API Change Detection

For as long as there have been APIs, the dreaded “unintended breaking change” has tortured API developers everywhere. Countless hours spent debugging, untold numbers of damage control meetings with unhappy customers, the inevitable “who broke the API?” finger-pointing; it’s not pretty.

And yet decades later, it still feels like it’s needlessly difficult for organizations to get good observability into how their API is changing. This is why we’re so excited to be tackling this problem head-on. Today’s release of API change detection is just the beginning.

Whenever there’s a change to your OpenAPI document, Speakeasy will automatically detect it and notify you. The changes will be summarized directly in your pull request, with a callout for when changes are breaking. If you want to dive into the details, head to our dashboard for the full breakdown.

import { SDK } from "@acme/cms";
import { Unrecognized } from "@acme/cms/types";

const cms = new SDK();
const post = await cms.posts.get('open-enums');

let icon: "📸" | "🎨" | "🏈" | "❓";
switch (post.category) {
  case "lifestyle":
    icon = "🎨";
    break;
  case "photography":
    icon = "📸";
    break;
  case "sports":
    icon = "🏈";
    break;
  default:
    post.category satisfies Unrecognized<string>;
    icon = "❓";
    break;
}

Open Enum Support

Both the power and the pain of enums come from their rigidity. Defining a fixed scope helps guide users towards intended use cases and makes enhanced type-safety possible. But the time will come when you need to alter the accepted values of an enum in your API, and it will be painful. How do you alter the set of accepted values without breaking existing code?

To soften the pain, some languages have native support for the concept of “open” enums (other languages don’t, but you can achieve the same results with custom classes). Open enums allow for unknown values to be passed through without erroring. For APIs that are rapidly evolving, this can help prevent some of the typical pain associated with making changes.

And now for TypeScript, Python and Go, Speakeasy supports open enums. You can use our new extension: x-speakeasy-unknown-values: allow and your SDK will generate a type that includes the enum values and a catch-all type that represents any unrecognized value. This allows you to handle unknown values gracefully in your code.

For the deep dive, read our release post

🚢 Improvements and Bug Fixes 🐛

NOTE

Based on the most recent CLI version: Speakeasy v1.297.0 (opens in a new tab)

The Platform

🚢 Standardize publishing secret names created by configure publishing command
🐛 Circular reference handling within unions
🐛 Don’t panic on bad validation lineNums
🐛 ClientCredentials hooks incorrect import
🐛 Mitigations for Github rate limiting
🐛 Nested namespaces in usage snippets

Typescript

🐛 Jest compatibility fixes and leaner error models for Typescript
🚢 Safer weakly typed unions

Go

🚢 Support Open Enums in Golang
🚢 Safer weakly typed unions
🚢 Support pointer request objects

Terraform

🚢 Improve terraform diff suppression by instantiating arrays to []
🐛 Fix Set datatype in Terraform

Java

🚢 Sandbox (Dev Containers) support for Java
🚢 Support for Server Sent Events
🐛 Correct logic when retries and pagination are used together

C#

🚢 .NET8 LTS support for C#
🚢 Simplify SpeakeasyHttpClient configuration
🐛 General Usage snippet reliability improvemenets
🐛 Flattened security field sanitizing in usage snippets C#

Python

🚢 Support Open Enums in Python