Handling breaking changes in SDKs

This guide explains how to handle breaking changes in APIs when using Speakeasy-generated SDKs. Follow these guidelines to maintain backward compatibility and ensure a smooth experience for your SDK users.

Safe changes

The following API changes are safe and won’t break existing SDKs:

Adding new fields

You can safely add new fields to API responses because older SDK versions ignore these fields. Adding new response fields doesn’t break existing integrations.

Adding new enum values

You can safely add new enum values when enums are marked with x-speakeasy-unknown-values (see our Customize enums documentation). Older SDKs handle these new values gracefully according to the behavior specified in the extension configuration.

Changes requiring caution

Some API changes require careful consideration to avoid breaking existing SDK implementations. Use the OpenAPI diff tool to identify potential breaking changes in your API specification.

Deprecating required fields

Take care when deprecating fields marked as required in the API specification. Older SDKs may throw validation errors if required fields are missing:

• Make the field optional before removing it.
• Plan a deprecation period for implementation updates.

Modifying oneOf schemas

Make changes to oneOf schemas carefully, as adding new variants may cause type mismatch errors in older SDKs:

• Maintain backward compatibility with existing schema variants.
• Test changes thoroughly with older SDK versions.

Future improvements

Speakeasy is developing additional features to help you manage breaking changes, including:

• SDK version upgrade prompts
• Improved tooling for breaking changes
• Enhanced version management capabilities