Interface Contract Evolution and Deprecation Policy
The Integration Hub defines a harmonised interface specification that integrators implement in their adapter layer. This specification constitutes a shared contract between Toqio and all active integrators. Because changes to this contract have direct implementation implications for every adapter in production, Toqio manages interface evolution through a structured process of classification, communication, and grace periods rather than through parallel versioning infrastructure.
This document describes how Toqio introduces changes to the harmonised interface, how those changes are communicated, and the obligations and timelines that both Toqio and integrators are expected to uphold.
Change classification
Not all changes to the interface specification carry the same risk. Toqio classifies every change into one of two categories before it is announced, as the category determines the communication and grace period requirements that apply.
Non-breaking changes
Changes that extend the contract without invalidating existing conformant implementations. Integrators are not required to act, though they may choose to adopt new capabilities.
Examples:
- Addition of new optional fields to existing request or webhook payloads
- Introduction of new webhook types not previously defined
- Addition of new optional endpoints to the harmonised interface specification
- Expansion of existing enumeration values with new members (integrators must implement tolerant readers — see Tolerant Reader principle)
Non-breaking changes are communicated proactively but do not carry a mandatory grace period obligation.
Breaking changes
Changes that require integrators to modify their adapter implementation to maintain conformance and avoid service disruption.
Examples:
- Addition of new mandatory fields to existing request or webhook payloads
- Removal or renaming of existing fields
- Changes to field types, formats, or enumeration values that alter existing semantics
- Removal or restructuring of existing endpoints in the harmonised interface
- Changes to authentication or security requirements (see Authentication)
- Changes to error response structures documented in Error Management
Breaking changes are subject to the full deprecation and grace period process described below.
Deprecation process
When a breaking change is identified, Toqio initiates a formal deprecation process before the change takes effect. The process involves collaboration between Technology, Product, and Delivery teams to assess technical feasibility and integrator impact prior to any announcement.
Process steps
1. Internal assessment
The change is evaluated internally to determine its impact severity (Low, Medium, or High) and the corresponding grace period. This assessment considers the breadth of integrators affected, the complexity of the required adapter changes, and any regulatory or contractual dependencies.
2. Official announcement
The change is officially announced to all active integrators and relevant stakeholders simultaneously. The announcement includes:
- A precise description of what is changing and why
- The impact classification
- The date from which the grace period begins (the announcement date)
- The date after which the deprecated behaviour will no longer be supported (the end-of-support date)
- Guidance on what integrators need to change in their adapter implementation
- Where applicable, the specification of the replacement behaviour
3. Grace period
The grace period begins on the announcement date. During this period, the existing behaviour remains fully supported alongside the new behaviour where technically feasible. Integrators must complete their adapter updates before the end-of-support date.
4. End of support
After the end-of-support date, the deprecated behaviour is no longer guaranteed. Integrators that have not completed their adapter updates by this date may experience service disruption.
Grace periods
Grace periods are determined by the impact severity of the breaking change, as assessed during the internal evaluation phase. The following reference periods apply:
| Impact severity | Definition | Grace period |
|---|---|---|
| Low | Limited scope — affects a small number of integrators or a non-critical path of the interface | 1.5 months |
| Medium | Moderate scope — affects multiple integrators or a commonly used interface path | 2.5 months |
| High | Broad scope — affects all or most integrators, or a critical path such as transaction processing or compliance flows | 4 months |
These periods represent the minimum committed notice from the official announcement date. Where circumstances allow, Toqio aims to provide additional time beyond the minimum.
The grace period is designed to allow integrators to complete a full development and certification cycle within their own release cadence. Integrators experiencing exceptional constraints should engage Toqio as early as possible after the announcement to discuss their specific situation.
Communication channels
Breaking change announcements and deprecation notices are delivered through communication channels established during the onboarding process. The specific channels are defined based on the operational needs and conditions of each integration, and may include both technical and business stakeholder contacts.
Integrators are responsible for ensuring that the contacts registered during onboarding remain current, and that announcements are routed to the appropriate technical teams within their organisation.
Non-breaking changes are communicated through the same channels and are also reflected in the interface specification changelog, which integrators should monitor as part of their ongoing integration maintenance.
Tolerant reader principle
Regardless of change classification, all adapter implementations should be designed according to the tolerant reader principle: the adapter must not fail when it encounters fields or enumeration values it does not recognise. Unknown fields should be safely ignored, and unknown enumeration values should be handled gracefully rather than treated as fatal errors.
This design principle is a prerequisite for non-breaking changes to be genuinely non-breaking in practice, and significantly reduces the operational risk associated with interface evolution for all parties.
Integrator obligations
Active integrators are expected to:
- Monitor announced changes through the established communication channels
- Assess the impact of each breaking change on their specific adapter implementation promptly after announcement
- Complete adapter updates and any required internal certification within the applicable grace period
- Engage Toqio proactively if a grace period cannot be met due to circumstances outside their control
- Maintain adapter implementations that conform to the tolerant reader principle at all times
Toqio's delivery team is available throughout the grace period to provide technical guidance and support for integrators undertaking adapter updates.