The Native & Search API supports both versioning and migrations, so Oath 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 Native & Search API.
The new v3 Native & Search 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 Native & Search 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.
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.
The Native & Search 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|
If you make a call to the Native & Search 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 will be versioned as part of the URL, shown below:
All the endpoints in the Native & Search 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 Native & Search API. There will be no minor versions released because non-breaking changes will be rolled into the current version.