Symitar creates a new API version every release and supports the latest four versions.
We advise clients who are new to SymXchange to use the latest version for new development.
When we update the SymXchange web service interface, existing SymXchange clients are affected. We use web services versioning to deploy the changes that affect clients so that clients have time to adapt to changes. There are two types of changes to the web service:
- Adding new operations to SymXchange.
- Adding new XML schema types that are not contained within previously existing types.
- Adding optional elements or attributes to existing request messages.
- Adding new optional elements (fields) to the end of an existing database entity element in the response. For the changes that are backward compatible, the SymXchange client does not have to do any code change.
Not Backward Compatible
- Removing an operation.
- Renaming an operation.
- Changing the parameters (in data type or order) of an operation.
- Changing the structure of a complex data type.
- Adding new required elements to existing messages.
- Removing required elements. To handle the changes that are not backward compatible, the SymXchange client must make code changes, which makes it a breaking change (see SymXchange Code Changes).
For the changes that are backward compatible, the SymXchange consumer does not have to make any changes to the code. However, to handle the changes that are not backward compatible, the SymXchange user will have to make changes to the code, which makes it a breaking change. There are separate URLs for different versions.
There will be a new endpoint every release, indicated by the release number. That endpoint will support all SymXchange services (create/read/update/delete [CRUD] and non-CRUD). If you want to use the updated version, you are required to enable it within System Web Console.
Example: 2019.01 Account Service endpoint:
A new API version will be introduced every release. Having multiple versions gives a SymXchange client time to upgrade. With versioning, clients can still be running the previous version and can decide when it is best to update their client code to the latest version.