API versions in Azure Search

Azure Search rolls out feature updates regularly. Sometimes, but not always, these updates require a new version of the API to preserve backward compatibility. Publishing a new version allows you to control when and how you integrate search service updates in your code.

As a rule, the Azure Search team publishes new versions only when necessary, since it can involve some effort to upgrade your code to use a new API version. A new version is needed only if some aspect of the API has changed in a way that breaks backward compatibility. Such changes can happen because of fixes to existing features, or because of new features that change existing API surface area.

The same rule applies for SDK updates. The Azure Search SDK follows the semantic versioning rules, which means that its version has three parts: major, minor, and build number (for example, 1.1.0). A new major version of the SDK is released only for changes that break backward compatibility. Non-breaking feature updates will increment the minor version, and bug fixes will only increase the build version.

Note

Your Azure Search service instance supports several REST API versions, including the latest one. You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. When using the REST API, you must specify the API version in every request via the api-version parameter. When using the .NET SDK, the version of the SDK you’re using determines the corresponding version of the REST API. If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.

Snapshot of current versions

Below is a snapshot of the current versions of all programming interfaces to Azure Search.

Interfaces Most recent major version Status
.NET SDK 9.0 Generally Available, released May 2019
.NET SDK Preview 8.0-preview Preview, released April 2019
Service REST API 2019-05-06 Generally Available
Service REST API 2019-05-06-Preview 2019-05-06-Preview Preview
.NET Management SDK 3.0 Generally Available
Management REST API 2015-08-19 Generally Available

For the REST APIs, including the api-version on each call is required. Using api-version makes it easy to target a specific version, such as a preview API. The following example illustrates how the api-version parameter is specified:

GET https://my-demo-app.search.windows.net/indexes/hotels?api-version=2019-05-06

Note

Although each request has an api-version, we recommend that you use the same version for all API requests. This is especially true when new API versions introduce attributes or operations that are not recognized by previous versions. Mixing API versions can have unintended consequences and should be avoided.

The Service REST API and Management REST API are versioned independently of each other. Any similarity in version numbers is coincidental.

Generally available (or GA) APIs can be used in production and are subject to Azure service level agreements. Preview versions have experimental features that are not always migrated to a GA version. You are strongly advised to avoid using preview APIs in production applications.

About Preview and Generally Available versions

Azure Search always pre-releases experimental features through the REST API first, then through prerelease versions of the .NET SDK.

Preview features are available for testing and experimentation, with the goal of gathering feedback on feature design and implementation. For this reason, preview features can change over time, possibly in ways that break backwards compatibility. This is in contrast to features in a GA version, which are stable and unlikely to change with the exception of small backward-compatible fixes and enhancements. Also, preview features do not always make it into a GA release.

For these reasons, we recommend against writing production code that takes a dependency on preview versions. If you're using an older preview version, we recommend migrating to the generally available (GA) version.

For the .NET SDK: Guidance for code migration can be found at Upgrade the .NET SDK.

General availability means that Azure Search is now under the service level agreement (SLA). The SLA can be found at Azure Search Service Level Agreements.