Handling breaking changes in SDKs

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

Safe changes

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

Adding new fields

Adding new fields to API responses is safe because older SDK versions ignore these fields. New response fields can be added without breaking existing integrations.

Adding new enum values

Adding new enum values is safe when enums are marked with x-speakeasy-unknown-values ([see enums customization doc]). 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

When deprecating fields marked as required in the API specification:

  • Older SDKs throw validation errors if the field is missing
  • Make the field optional before removing it
  • Plan a deprecation period for implementation updates

Modifying oneOf schemas

Make changes to oneOf schemas carefully:

  • 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 manage breaking changes:

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

Note

For more information about SDK versioning and how Speakeasy handles version bumps, see our SDK versioning guide.