Versions for Web Services
This page describes how Yahoo! Search Web Services manage version changes.
Why Versions?
One of the advantages of using Web Services rather than scraping HTML from web pages is that the provider agrees that the content being returned will consistently remain in the same structure. In fact that structure is explicitly described by a schema. However, there are times when we wish to update the existing services to add new functionality. If we just changed the request arguments required and the form of the return structures, it is possible that applications that make use of these services would break. We address this problem by versioning our web services.
How Versions Work
Yahoo! Search Web Services are versioned. When we release an API, it has a version number associated with it, and the structure of the inputs and outputs of that particular version of the service will not change. Consider the Image Search service. If you visit the image search documentation page you will see the Request URL has a version embedded in it. For example, http://search.yahooapis.com/ImageSearchService/V1/imageSearch
If we decide to add new capabilities to the ImageSearchService, we will create a new version (V2), and provide those new capabilities via a new URL. The old URL will continue to function as it did prior to the release of V2 for some time, so any existing applications that make use of the V1 API will also continue to work. Note that the separate services may update their versions independently, so when the ImageSearchService updates to V2, the VideoSearchService may have already moved to V5. We will announce new versions of services on our announcement mailing list, and you can always consult the documentation pages to discover the latest versions of any API.
At times we will retire old versions of APIs. Before doing this we will announce the retirements on our announcement mailing list at least two months beforehand. Applications calling a retired version will receive an error message like this.