Developer portal
Versioning and deprecation
Compatibility guarantees and retirement policy for reliable long-lived integrations.
Last updated: 2026-06-09
Version strategy
Qtangl publishes stable HTTP contracts under versioned paths. Integrations should pin to a documented major version and tolerate additive fields. This preserves forward compatibility while allowing feature growth.
What is considered breaking
| Field | Type | Required | Description |
|---|---|---|---|
| Additive response fields | non-breaking | Yes | New optional fields may be added at any time. Clients should ignore unknown keys. |
| Required request field changes | breaking | Yes | Any new required request parameter requires a new major API version. |
| Enum value expansion | non-breaking | Yes | Additional enum values can appear; client parsers must avoid strict closed-set assumptions. |
| Path or semantic contract changes | breaking | Yes | Behavioral changes that alter endpoint meaning require a new version and migration guide. |
Deprecation policy
| Field | Type | Required | Description |
|---|---|---|---|
| Announcement | T-90 days target | Yes | Deprecation notice posted to docs changelog and account contacts with migration guidance. |
| Deprecation headers | active period | Yes | Responses include deprecation metadata and target sunset date where supported. |
| Sunset | retirement date | Yes | Deprecated endpoint or field is removed or disabled after the published sunset window. |
Communication channels
- Documentation changelog entries for all externally visible API contract changes.
- Direct outreach to tenant admins for major deprecations and security-sensitive updates.
- Migration examples and replacement endpoint references when behavior changes.
Track upcoming changes on docs changelog.
Found an issue? Report documentation feedback