Versioning FAQ

1. What is "versioning"?

   "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.

2. 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 patches for bug fixes are implemented.

3. How are versions and namespaces designated?

   EWS uses the following versioning scheme for releases: Version major.minor.patch (Version 1.0.0):

   • A major version is released for backward-incompatible changes. In a production environment, these changes would have the effect of breaking client implementations that have been compiled against the earlier version of the web services.
   • 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 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

4. Where will the new version be served?

   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.

   • 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 updates.

   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

5. How do I know what has changed?

   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.

6. Which changes are backward compatible and which changes 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.

   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.)

7. 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, we will notify you.

8. Will new versions be available in the sandbox?

   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.

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

   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.

10. What should I do first?

    Anytime we launch a new version of the web services, 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 in production before the old version is removed.
11. When can I start using the new version in production?

    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.

12. 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 launches, we will communicate the actual date when the old version will be removed from the EWS sandbox and production.

13. 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, 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.