NZ Post Group is committed to continuously improving and expanding the services it provides its customers. Where possible, NZ Post will make changes to the API but not change the version number because the changes are considered to be "non-breaking" for you, the consumer.
Non-breaking changes can include:
API implementation changes that do not change the API interface Addition of new resources
Addition of new non-mandatory request parameters of attributes Addition of new data fields returned in the response
* Change in the order of data fields returned by the API
API application developers should develop their code so that these types of changes will not break their application
From time to time new versions of existing API’s will be created to include enhancements or new features relating to our parcel services. Changes that are considered a breaking change and require a version change are:
Renaming of resources, parameters, attributes Inclusion or removal of mandatory parameters
* Restructuring of the API interface
As upgrades of the API’s are made available to our integrators, the version number will be incremented. Upon release of a new version, your applications can continue to use the current version while you assess the need to upgrade. Release notes will be provided with every release describing the change and its impacts in detail.
Upon upgrading, integrators are encouraged to execute their own regression tests against the new API version deployed to Production, prior to upgrading to the new API version in their own production. If the integrators wish to test in UAT environment, they will need to check with NZ Post Group if the environment is ready for testing.
Customers are asked to maintain a version within 2 major releases of the latest version to ensure that the highest quality of service is provided to you and to your own customers.
Older versions of the API’s will be deprecated, meaning that they will be available for use by existing customers but they will not be available to new customers.
From time to time, a legacy version of an API will be decommissioned. Users of the legacy version will be contacted directly regarding an upgrade time frame.