Versioning

Yahoo Gemini API now supports both versioning and migrations, so partners and developers can roll out changes over specific periods of time when integrating with the API.

API versioning has been supported since the initial v1 release of the Gemini API.

v3 API

The new v3 API provides partners with these advantages:

  • Support for Upgraded URLs (UUs). For more information on Upgraded URLs (UUs) in v3, refer to Upgraded URLs.
  • Greater API object stability, as well as improved management of API changes, building on the enhancements in v2 Gemini API.
  • Support for Site X Device Targeting with new available targeting attributes. For more information, refer to Targeting Attributes.
  • Additional bug and error fixes for improved performance and stability.

v2 API

The v2 API provided partners with a number of advantages:

  • Improved management of API changes: for example, improved handling of backward-incompatible features
  • Faster introduction of new feature releases, like the rapid introduction for v2 of a new object type, shared sitelink
  • Smoother transitions to support older API functionalities, specifying exact dates for deprecation and End of Life (EOL)

Advance Notice for Developers

Developers will receive advance notice when the API changes.

  • What’s New will provide information on new features and changes in release schedules, as needed.
  • The Partner Support page will also provide you with a quick snapshot of recent and upcoming releases.

Release Schedule

The Gemini v3 API was released on 25 July 2017. V2 is still supported post-release. Official deprecation for the v2 API has not yet occurred. Partners and developers will be notified once this has been officially determined, and a schedule provided.

The schedule for the v3 release is shown in the table below, as well as dates for the v1 deprecation.

API version Release date Deprecation date End of Life (EOL) Migration path
v3 25 July 2017      
v2 1 June 2016      
v1 1 September 2015 1 September 2016 1 September 2017 Migrate to v2

Developer Impact

If you make a call to the Gemini API without specifying the version, a 404 error will be returned.

All breaking changes will be rolled into the new version. Support for multiple versions of the API is still maintained, even if different versions provide different levels of functionality.

v3 Endpoints

v3 endpoints will be versioned as part of the URL, shown below:

Resource URI

https://api.gemini.yahoo.com/v3/rest/{resource}

All the endpoints in the Gemini API have been updated to v3. The v2 version of the API is still available by clicking on the links in this documentation table of contents.

Version Numbering System

The new version numbers are for major releases of the Gemini API. There will be no minor versions released because non-breaking changes will be rolled into the current version.