We design our APIs to be stable and backwards compatible. Breaking changes are avoided whenever possible, but when necessary, they follow a structured versioning and deprecation strategy.
- Non-breaking changes (do not require a new version):
- Adding new optional fields
- Adding new endpoints
- Expanding valid values (without changing existing ones)
- Breaking changes (require deprecation and possibly a new version):
- Removing or renaming fields or endpoints
- Changing response formats in incompatible ways
- Altering existing request/response semantics
- Versioning model:
- Each major API version (e.g., v1, v2) is supported independently.
- New major versions introduce improvements but may not be backwards compatible.
- Deprecated versions remain available for a defined period, after which they are sunset. See Deprecation
- Design integrations to handle additive changes (e.g., ignore unknown fields).