Enterprise Web Services: Versioning

What is versioning?

Versioning refers to the release of a new version of EWS. Depending on the type of release, the new version may include new URLs, WSDLs, end-points, and a new namespace.

Why create a new version?

A new version is required when:

• changes are made to the components - services, operations, parameters, and so on, or
• when bug fixes are made.

How are versions and namespaces designated?

EWS uses the following versioning scheme for releases: Version major.minor.patch. For example, Version 1.0.0.

• A major version is released for backward-incompatible changes. In the production environment, these changes would have the effect of breaking client implementations that have been compiled using an earlier version of the webservices.
• A minor version is released for backward-compatible API changes.
• A patch version is released for all other backward-compatible changes.

EWS uses the following designation for namespaces: Vmajor (V1).

Each time a EWS major version is released, namespace is updated. Examples of possible EWS versions and the corresponding namespaces are given below:

Where will the new version be served?

For all releases, the new version of the webservices will be hosted at the same colocations as the older versions of the webservices.

• A major version will require new URLs, WSDLs, end-points, and a new namespace.
• A minor version will require new WSDLs only.
• A patch version does not require any update.

The following 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 the same as that of 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)

How do I know what has changed?

The release notes, included with the EWS documentation, helps you understand the changes in the webservices and how these changes may impact your implementation. The release notes highlight the changes between versions and also discuss the changes within each version.

Which changes are backward compatible and which are backward incompatible?

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.

What happens when a component is removed?

Occasionally a service, but more likely an operation or data object, will be marked for removal. When this happens, the component will be in a deprecated state and will be available for use for the duration of the current major version. You can use this time to update your client application as needed. When the next major version is released, the component will be removed.

Will my license and quota work for both versions?

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, you will be notified.

Will new versions be available on the EWS sandbox?

Yes, new versions will be released on the EWS sandbox as well as on production. Use the EWS sandbox to test your implementation before moving your client application to production.

Why are you launching a new version in production even before I've had a chance to test it?

We often launch a new version on production to bring you the new changes as soon as possible. This way, if you have an immediate need for the new functionality, you may choose to begin your implementation immediately.

What should I do first?

Anytime we launch a new version of the webservices, we recommend that you follow this general process:

• Read the release notes to understand what has changed.
• Experiment with the new version in the EWS sandbox, make changes to your client application, and then test your implementation.
• Be ready to switch to the new version on production before the old version is removed.

When can I start using the new version in production?

We suggest that you first test your implementation on the EWS sandbox. Once you are ready, and if the new version is available in production, you can start using it immediately.

When will old versions be removed?

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 is launched, we will communicate the actual date of the removal of the old version from the EWS sandbox and production.

None of the changes affect my application--what do I need to do?

For major version releases, you must recompile your client application or manually update your script to point to the new namespace. After that perform a full regression test on the EWS sandbox before switching 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.