Versioning

Some Business Profile APIs are available in more than one version and release channel. The version is the segment of the request URL that follows the hostname, such as v1 or v1alpha. This page explains how versions are numbered, how stable each release channel is, and how to call the alpha channel.

Version numbering

Each API version has a major version number and an optional channel suffix:

  • Major version (v1, v2, ...): A stable, generally available version. A major version only receives backward-compatible changes, such as new methods, new fields, or new enum values. Changes that aren't backward compatible are released in a new major version.
  • Alpha channel (v1alpha, v2alpha, ...): A pre-release channel of a major version. It includes everything in that major version, plus features that haven't reached general availability yet.

Release channels

Channel Stability Contents
General availability (v1) Stable. Changes within a major version are backward compatible. When a major version is deprecated, it remains available for at least 12 months after the deprecation announcement. Deprecations and sunset dates are published on the Deprecation schedule page. Generally available features.
Alpha (v1alpha) Pre-release, with no stability commitment and no defined lifespan. Alpha features can change or be discontinued with at least 30 days' notice. Don't use alpha features in production integrations. Everything in v1, plus features that haven't reached general availability yet.

How features move between channels

When a feature graduates from v1alpha to v1, it remains available in v1alpha.

Guides and reference pages for features that are available only in v1alpha are marked as alpha. New alpha and generally available features, and changes to or removals of alpha features, are announced in Latest updates and in the change log for each API.

Use the alpha channel

To call the alpha channel, replace v1 with v1alpha in the request URL. For example:

GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}

Both channels belong to the same API, so they share the following:

  • API enablement in the Google Cloud console.
  • OAuth 2.0 scopes and access requirements.
  • Resource names, such as locations/{locationId}.
  • Quota. Requests to v1 and v1alpha count against the same per-project quota. For details, see Quota limits.
  • The underlying business data. Changes that you make through v1alpha are visible through v1, and the other way around.

Client libraries and the public API directory include v1 only. To call v1alpha, send REST requests directly.

Best practices

  • Use the stable version, such as v1, for production integrations.
  • Use the alpha channel, such as v1alpha, to adopt new features before they reach general availability. To share feedback, see Support.
  • Make your client tolerate fields and enum values that it doesn't recognize.
  • Before you build on an alpha feature, check its guide and the change log for known limitations.