Forward compatibility

This guide explains how Speakeasy-generated SDKs maintain forward compatibility when APIs evolve. Forward compatibility ensures older SDK versions continue to work correctly when the API adds new fields, enum values, or other data.

Forward compatibility at a glance

Common forward compatibility scenarios

This section covers the most frequent scenarios encountered when evolving APIs and how Speakeasy handles them to maintain forward compatibility.

Handling new fields

Adding new fields to API responses is safe because older SDK versions ignore these fields. When an API response includes fields not defined in the SDK’s model, these fields are simply not deserialized.

Older SDK versions will continue to work without errors, ignoring the updated_at field. This allows APIs to evolve by adding new data without breaking existing integrations.

Handling new enum values

APIs often need to add new enum values over time. Speakeasy provides the x-speakeasy-unknown-values extension to handle this gracefully.

When the API adds a new enum value (e.g., suspended), older SDK versions handle it according to the language:

• TypeScript
• Python
• Go
• Java

This prevents runtime errors when new enum values are encountered, allowing APIs to add new states without breaking existing clients.

Handling unexpected data

Speakeasy-generated SDKs include built-in mechanisms to handle unexpected data:

1. Validation errors: SDKs provide detailed validation errors when unexpected data is received, making debugging easier

2. OneOf schemas: When using oneOf schemas, SDKs can handle evolving data structures by attempting to match against known variants

3. Optional fields: Fields marked as optional in the OpenAPI spec won’t cause validation errors if missing

Handling unexpected response codes

APIs evolve over time and may introduce new response codes. Speakeasy-generated SDKs are designed to handle unexpected response codes gracefully:

Benefits of status code ranges

1. Flexible status codes: Using 2xx and 4xx patterns allows APIs to add new specific status codes (like 201 or 429) without breaking existing SDKs

2. Consistent error handling: All error responses follow the same structure, making it easier to handle new error types

3. Graceful degradation: Even when encountering unexpected status codes, SDKs can still extract useful information from the response

When an API returns a status code that wasn’t explicitly defined in the original specification, Speakeasy SDKs:

• Match it to the appropriate range (2xx, 4xx, 5xx)
• Parse the response using the defined schema for that range
• Provide access to both the status code and response body

Advanced forward compatibility techniques

These advanced techniques help maintain forward compatibility in more complex scenarios.

Deprecating fields

When evolving APIs, deprecating fields is a common necessity. Speakeasy provides extensions to handle field deprecation gracefully while maintaining forward compatibility:

Benefits of proper deprecation

1. Fields remain accessible to older SDK versions
2. New SDK versions mark these fields with proper deprecation annotations
3. Generated documentation includes deprecation notices
4. Developers receive clear guidance on migration

Field removal process

When planning to remove a field entirely:

1. Mark the field as optional first
2. Add deprecation notices with the deprecated keyword and x-speakeasy-deprecation-message
3. Allow sufficient time for users to update implementations
4. Remove the field only after a suitable deprecation period

Forward-compatible unions

To create forward-compatible unions that can handle new data types added in the future, use the oneOf pattern with a string fallback:

Benefits of string fallback

1. Provides strongly typed handling for known variants (dog and cat types)
2. Gracefully captures any future variants as string values
3. Prevents runtime errors when new variants are introduced
4. Allows SDK users to handle unknown variants safely

Guard-rails for breaking changes

Speakeasy provides several tools to detect and prevent breaking changes:

Version your API

Create a versioning strategy for your API to manage breaking changes:

• Use path-based versioning (e.g., /v1/resource, /v2/resource)
• Include version in request headers (Api-Version: 2023-01-01)
• Maintain multiple API versions simultaneously during migration periods

Add defaults for optional fields

When making required fields optional:

• Always include default values to maintain backward compatibility
• Document the default behavior clearly
• Use the default property in your OpenAPI specification:

Open your enums

Convert closed enums to open enums using the Speakeasy extension:

Use the OpenAPI diff tool

The OpenAPI diff tool identifies potential breaking changes between API specification versions:

This highlights changes that might break backward compatibility, such as:

• Removing required fields
• Changing field types
• Modifying oneOf schemas

SDK version management

Speakeasy automatically manages SDK versioning based on the nature of changes:

• Patch version for non-breaking changes
• Minor version for backward-compatible additions
• Major version for breaking changes

Breaking change notifications

When generating SDKs, Speakeasy detects breaking changes and provides clear notifications about what changed and how to handle the transition.