The ZOLOZ service versions an API in the way of including the version number in the HTTP URI path, for example, https://zoloz_api_host/api/v1/products.
Usually compatible changes might be introduced into an existing version of an API, while a new version of an API is provided when incompatible changes are introduced.
When a new version is released, the customers can choose to continue using the existing version or upgrade to the new one. If continue to using the existing version, the customer must properly handle the compatible changes to the API.
The possible compatible changes to an existing version are listed as below:
A new optional field is added to the request.
A new valid value is defined for a request field.
The maximum length that is allowed for a request field increases.
A new field is added to the response.
The order of the fields of the request or the response changes.