Developer support
      Back to home
      1. Knowledge base
      2. Developer support

      Wazoku Open API Backwards Compatibility Policy

      This article describes the backwards compatibility policies for the Wazoku Open API.

      Backwards Compatibility

      As our Open API evolves, Wazoku will make reasonable efforts to notify you of breaking changes in advance with sufficient time to adapt to these changes. However, we may make changes without prior notice if the change is considered non-breaking, or if it is a breaking change being made to address critical product bugs or legal, security, or privacy concerns.  

      Definition of breaking and non-breaking changes

      A breaking change is a change that may require you to make changes to your application in order to avoid disruption to your integration. The following are a few examples of changes we consider breaking: 

      • Change or Remove an authentication mechanism

      • Renaming a response field

      • Addition of a required parameter without default values

      • Change in the functionality of an endpoint. For example, if a DELETE request was previously used to archive the resource but now hard deletes the resource.

      • Introduction of a new validation mechanism such that a previously accepted input is now rejected

      • Removal of any HTTP methods for a resource endpoint

      A non-breaking change is a change that you can adapt to at your own discretion and pace without disruption. In most cases, we will communicate non-breaking changes after they are already made. Please ensure that your application is designed to be able to handle the following types of non-breaking changes without prior notice from Wazoku: 

      • Addition of new endpoints

      • Addition of new methods to existing endpoints

      • New fields in responses

      • New optional request fields or parameters

      • New required request fields that have default values

      • Addition of a new value returned for an existing text field

      • Changes to the order of fields returned within a response

      • Addition of an optional request header

      • Removal of redundant request header

      • Changes to the length of data returned within a field

      • Changes to the overall response size

      • Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.

      • Fixes to HTTP response codes and error codes from incorrect code to correct code

      Versioning 

      Whenever a breaking change or a non-backward compatible change is made to the Wazoku Open API, a new version will be introduced. Earlier versions will continue to function and will be deprecated and decommissioned according to the deprecation policy.  

      Deprecation policy and time frames 

      Wazoku Open API versions being decommissioned will be marked with a Deprecation HTTP response header in line with the IETF guideline. The form of the deprecation header will be Deprecation: version="version", date="<deprecation date>".  Any deprecated Open API versions will be available and supported in their original form for 6 months before it is decommissioned. Clients will also be notified using a mailing list and are encouraged to subscribe to the mailing list.

      See also