Developer Guides
API Stability Levels

API Stability Levels

Stability Levels indicates maturity, expectations of changes and support policy for APIs and software libraries.

They provide developers and users with a clear understanding of what to expect when integrating or depending on a given version.

The stability levels are:

  1. alpha Rapid-iteration development phase, useful for previewing APIs to partners.
  2. beta Feature-complete but still under testing and could receive more changes.
  3. stable A production-ready and fully supported API.

Levels

alpha

Denote the rapid-iteration development phase of this component.

  • Usage:
    • Previewing APIs, share progress and gather feedback.
    • Collaborating with partners who can integrate changes on short notice.
  • Expectations: Breaking changes can happen without changing major version
  • Deprecation: No past-version support or deprecation policy when changes are made.

beta

Feature-complete but under testing.

  • Usage: API testing with broader set of partners.
  • Expectations:
    • Betas should be as stable as possible, but can still receive changes.
    • Breaking changes are allowed if absolutely necessary, but only with a deprecation policy and transition period.
  • Deprecation: API must remain supported for 6 months after being declared deprecated, to provide users the opportunity to migrate their code.

stable

A production-ready and fully supported API.

  • Usage: General availability for all users
  • Expectations:
    • No breaking changes without incrementing the major version.
    • Bugfix and security patches are expected to ensure ongoing reliability.
  • Deprecation: API must remain supported until all users migrated to alternative versions, or until agreed between API provider and customers.

Format

The stability level of an API or software is communicated through the version number associated to each specific release:

  • For alpha and beta stability levels, a suffix is appended to the version number.
  • stable releases do not have the stable suffix.

Shorthand format

The shorthand format abbreviates the version to vX, focusing on the “API compatibility” of the release (which is expressed by the MAJOR number of the SemVer format.)

  • During alpha and beta stages, the identifier is appended to the shorthand format.
    Example: v1beta, v1alpha, or v1alpha1, v1alpha2.
  • When the API reaches stable maturity, the identifier stable is not appended and the versions are reported as vX.
    Example: v1, v2.

SemVer format

The SemVer format is used when it’s important to refer to a specific release or build, not just the “API compatibility” but also a specific set of minor changes and bugfixes.

In the SemVer specification, alpha and beta versions are referred as pre-release versions (https://semver.org/#spec-item-9), and they are characterized as versions that are unstable and do not have compatibility requirements.

Following the above specification:

  • Pre-release versions (alpha and beta stability levels) are denoted by appending a hyphen and an identifier.
    Example: 1.0.0-beta, 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-alpha.2
  • When the API reaches stable maturity, versions are reported without -alpha or -beta suffixes. Example: 1.0.0, 1.0.1, 1.2.3

References

Semantic VersioningBackward Compatibility