"Versioning" refers to the publication of a new version of the web services. Depending on the type of release, the new version may include new URLs for the WSDLs and end-points as well as a new namespace.
A new version is required when changes are made to the components (services, operations, parameters, and so on) or when patches for bug fixes are implemented.
EWS uses the following versioning scheme for releases: Version major.minor.patch (Version 1.0.0):
EWS uses the following desigination for namespaces: Vmajor (V1). The namespace is updated each time EWS releases a major version.
| Version | Namespace |
|---|---|
| Version 1.0.0 | V1 – major version release |
| Version 1.0.1 | V1 – patch release, no changes |
| Version 1.1.0 | V1 – minor release, backward-compatible API changes |
| Version 1.1.1 | V1 – patch release, no changes |
| Version 1.2.0 | V1 – minor release, backward-compatible API changes |
| Version 2.0.0 | V2 – major version release, backward-incompatible changes |
| Version 2.0.1 | V2 – patch release, no changes |
| Version 3.0.0 | V3 – major version release, backward-incompatible changes |
| Version 3.1.0 | V3 – minor release, backward-compatible API changes |
For all releases, the new version of the web services will be hosted in the same co-locations as the old version of the web services.
These examples show how the URLs for the LocationService change during a major version release. Although the WSDLS have been updated, the URLs for the new version are essentially the same as the old version, with the exception of the namespace designation.
Sandbox
https://sandbox.marketing.ews.yahooapis.com/services/V1/LocationService?wsdl – for Version 1.x.x
https://sandbox.marketing.ews.yahooapis.com/services/V2/LocationService?wsdl – for Version 2.x.x
Production
https://global.marketing.ews.yahooapis.com/services/V1/LocationService?wsdl – for Version 1.x.x
https://global.marketing.ews.yahooapis.com/services/V2/LocationService?wsdl – for Version 2.x.x
The release notes, included with the EWS documentation, will help you understand what has changed in the web services and how these changes may impact your implementation. The release notes will highlight the changes between versions and also discuss the changes within each version.
Backward compatible and incompatible changes are shown in the table below, listed by component. Backward-compatible changes are released with minor versions or patch versions. Backward-incompatible changes are released with major versions.
| Component | Backward Compatible | Backward Incompatible |
|---|---|---|
| Service | Add a new service. | Remove an existing service. |
| Operation | Add a new operation. | Change or remove an existing operation. Change an operation's command group or authorization. |
| Parameter | Add a new parameter; change or remove an existing parameter. | |
| Response | Change an existing response. | |
| Data object | Add a new data object | Change or remove an existing data object. |
| Element | Add a new element; change or remove existing element. Change an element's restrictions (required or optional.) |
Yes, your license and quota will work for both versions, and you do not need to make any changes. However, the quota is shared between the versions. Also, operations added to the new version, or changes to the command group assignment for an operation, may require a change to your license configuration. If this is necessary, we will notify you.
Yes, new versions will be released to the EWS sandbox as well as to production. Use the EWS sandbox to test your implementation before moving your client application to production.
We often launch a new version in production to bring you the new changes as soon as possible. That way, if you have an immediate need for the new functionality, you may choose to begin your implementation immediately.
Anytime we launch a new version of the web services, we recommend that you follow this general process:
We suggest that you first test your implementation in the EWS sandbox. Once you are ready, and if the new version is available in production, you can start using it right away.
We are committed to keeping two incompatible versions live (for example, Version 1.0.0 and Version 2.0.0 or Version 1.0.0 and Version 2.1.0). We will determine the timeframe for supporting the old version based on the complexity of the changes. When the new version launches, we will communicate the actual date when the old version will be removed from the EWS sandbox and production.
For major version releases, you must recompile your client application or manually update your script to point to the new namespace, and then perform a full regression test against the EWS sandbox before making the switch to production. For minor and patch version releases, even if the changes in the new version do not affect your implementation, we recommended that you follow the same procedure.