Backwards Compatibility

The Weave API is versioned to give you confidence that your integrations will continue to work. This page describes what we consider a breaking change and what we guarantee will remain stable within a given API version.

Versioning

The API version is included in the URL path. For example:

/analytics/v1/smsMessages:search

A new major version (e.g. v1 → v2) signals a breaking change. When a new major version is released, the previous version will continue to function for a period of time to allow for migration.

What is guaranteed to be stable

Within a given major version, the following are guaranteed not to change:

  • Existing field names and their types in both requests and responses.
  • Existing endpoint paths and HTTP methods.
  • The meaning and behavior of existing fields and parameters.
  • Existing enum and constant values.

What may change without a major version bump

The following changes may occur within a major version and are not considered breaking:

  • New optional fields may be added to request bodies. Existing integrations that do not send these fields will continue to work.
  • New fields may be added to response bodies. Clients should ignore unrecognized fields rather than treating them as errors.
  • New values may be added to enums or constant sets returned in responses. Clients should handle unknown values gracefully rather than failing.

What is always a breaking change

The following changes will never be made without a major version bump:

  • Removing or renaming existing request or response fields.
  • Changing the type of an existing field.
  • Removing or renaming an endpoint.
  • Adding new required fields to a request.

Recommendations for client implementations

To write a resilient integration:

  • Ignore unknown fields in responses - new fields may appear at any time within a major version.
  • Handle unknown enum values in responses - new values may be added within a major version.
  • Do not rely on undocumented fields or behavior - only documented behavior is covered by this guarantee.