Versioning and Changes
Effective versioning and change management are critical to maintaining a robust and reliable API. This section outlines the principles and practices we follow to ensure seamless updates and clear communication regarding any modifications to the Connect API.
Non-Breaking Changes
Non-breaking changes are updates to the API that do not affect the existing functionality or disrupt the current integration. These changes are generally additive or corrective and are implemented to enhance the API's performance and capabilities without requiring any modification to existing client code.
Examples of Non-Breaking Changes:
Additive Functions:
- Introduction of new endpoints, parameters, or fields that do not interfere with existing ones.
- Bug Fixes: Corrections to the API that resolve issues or improve stability, ensuring better performance without altering the existing contract.
Best Practices for Integrating Non-Breaking Changes:
Avoid Dependency on Order:
Ensure that your integration does not rely on the sequence of returned items. This practice safeguards your implementation against any changes in the order of data provided by the API.
Utilise Optional Parameters:
Take advantage of optional parameters and fields, which allow for backward compatibility and gradual adoption of new features.
Breaking Changes
Breaking changes are modifications to the API that alter its current functionality and may disrupt existing integrations. These changes typically involve significant updates that change the API's contract, such as removing or renaming endpoints, parameters, or fields.
Examples of Breaking Changes:
Endpoint Removal or Renaming:
Deleting or changing the name of an endpoint can break existing integrations that depend on it.
Parameter or Field Modification:
Changing the structure, type, or required status of parameters or fields in a way that is incompatible with previous versions.
Managing Breaking Changes:
Major Version Updates:
Breaking changes will trigger a major version number update (e.g., from v1.x.x to v2.0.0). This signals to all stakeholders that significant changes have been made that may require updates to their integration.
Communication with Stakeholders:
It is essential to communicate any breaking changes well in advance to all stakeholders. This communication should include detailed information about the changes, their impact, and the necessary steps to adapt to the new version.
This notification would normally be communicated by your product/contract manager.
Best Practices for Handling Breaking Changes:
Deprecation Notices:
Deprecation notices for features that will be removed or changed will be highlighted in the documentation as soon as they are known. This gives stakeholders time to transition to the new version.
Clear Documentation:
All changes will be thoroughly documented, with clear instructions on how to migrate from the old version to the new version.
Conclusion
All Changes will be documented in the Change Log so that a clear and auditable history is visible to all customers.
Adhering to these principles for versioning and change management, we aim to provide a stable and predictable experience for all users of the Connect API.
Non-breaking changes enhance the API's functionality without disrupting existing integrations, while breaking changes are carefully managed and communicated to ensure a seamless transition to new versions.
Our commitment to clear communication and thorough documentation helps maintain trust and reliability in our API offerings.