Skip to content

Versioning

Breaking changes to published API versions can disrupt consumers, so our policy is to ensure that breaking changes are only published with a major version change. Additionally, release notes must accompany each major and minor release.

See below for what constitutes a breaking change.

Requirement

  • External APIs must increment the major version within their URI if they introduce a breaking change.
  • Internal APIs with over one consumer must increment the major version within their URI if they introduce a breaking change.
  • Release notes must accompany each major and minor release.

Guidance

  • It is optional to increment the major version within their URI when introducing a breaking change if it is an internal API with only one consumer AND if the consumer’s clients can be updated at the same time as the API. An example of this would be a web app pushed out to all clients vs. a mobile app where updates roll out more slowly.
  • It's optional but recommended to publish release notes for patch versions.

Breaking change definition

At a high level, a breaking change is any change to an API that would cause an error in a consuming application. The following are all examples of breaking changes:

  • Removing an endpoint
  • Renaming an endpoint’s path
  • Removing an HTTP verb (GET, POST, and so on) for an endpoint
  • Removing a property
  • Renaming a property
  • Changing a properties-level or tier within an object’s hierarchy
  • Making a previously optional request body property required
  • Changing a property’s type
  • Changing a property’s format
  • Adding or removing values from an enum
  • Adding a new required query parameter to an endpoint
  • Removing a query parameter from an endpoint
  • Adding a required scope to an existing endpoint
  • Removing a scope from an existing endpoint

API versioning scheme

Requirement

  • APIs must only use URI (non-header)-based major versioning.
  • APIs must provide a major version number in the URI path after the namespace and before any resources/operations.
  • The versioning scheme must start with the lowercase character v followed by an integer, the combination of which produces an ordinal number, e.g. v0, v1, v2.
  • APIs must NOT expose minor or patch version numbers in the URI path.
  • A minor API version must maintain backward compatibility with all previous minor versions within the same major version.
  • For non-major changes, API teams must still update the minor or patch versions in the OAS documentation.

Guidance

  • Versioning should start at v0.

The major version after the namespace.

https://api.va.gov/benefits/v0

Resources or operations specific to the endpoints within the API then show up after the version number.

https://api.va.gov/benefits/v0/claims

Incrementing minor and patch versions

Requirement

  • Backward-compatible changes that introduce new endpoints or new fields within existing endpoints must be released within a new minor version.
  • Changes to the API's underlying service, or upstream services, that do not update its interface or cause any new side effects to the underlying system's data must be released as a patch version.
  • Minor version releases must not change the major version within the URI.

Guidance

  • Creating a new OAS doc for each minor version can result in many files that are virtually the same. Use 'reference definitions', $ref, to reduce duplication and share definitions across OAS docs.

As minor and patch version information is not in the URI path, minor changes must only be documented in the OAS doc for the API.

Before
info:
  title: Benefits API
  ...
  version: 1.0.0
After
info:
  title: Benefits API
  ...
  version: 1.1.0

Number of active versions

Guidance

  • API teams should aim to have one active version of an API.
  • At most, API teams should not have more than two active versions of an API.

The best practice is to have one active version of an API at a time. However, there might be situations where maintaining multiple active versions is necessary. An example would be a team modernizing a large legacy API and rolling out the new version's endpoints over time. In that case, keeping the older version active may be necessary until the new version has reached parity.