API Versioning

All Vonage APIs must support versioning. This allows customers to understand which API requests and responses to expect, and to allow customers to migrate from one version to another more easily.

Version numbers follow the general ideas of SemVer, with the change that we only report the MAJOR version. For example, if an API is at version 1.5 internally, the route will be /v1/product/endpoint. If a backward compatible change is introduced, internally we may incremement the API to 1.6 but the API route will stay /v1/product/endpoint.

For products that are not generally available, they follow the rules of "Version 0" versioning, and allow breaking changes at the MINOR version. For example, if an API is in beta and internally versioned at 0.12.1, the route would be /v0.12/product/endpoint. If a backward incompatible change is introduced, the version number may increment to v0.13.0, and the route would change to /v0.13/product/endpoint.

In general, Vonage follows a few rules when it comes to determining if a version change is necessary:

  1. If a change requires a developer to change their code, this is a backwards incompatible change.
  2. Purely additive changes, such as new optional keys in a response, are backwards compatible.
  3. Subtractive changes, such as removing any key from a request or response, are backwards incompatible.
  4. Changing optional keys to mandatory keys in a request or response are backwards incompatible.

If you are unsure whether a change is backwards compatible or incompatible, you can reference Specmatic's Backwards Compatibility Rules and compare what you are doing to the chart. Do note that, while the chart offers exceptions, please try and keep exceptions to a minimum. Changes like making an optional key non-operational can lead a user to a false expectation of how the API works or should respond.

Structure

The version is given in the URI. The format for versioning is https://<HOST>/v<VERSION>/<ENDPOINT>.

The only time we update an API's version is when a backwards compatibility break is made. Due to this, Vonage APIs only support major API versions e.g. /v1, /v2

APIs that are not considered Generally Available (GA) must use the /v0.x format for denoting their version, such as /v0.1, /v0.2, etc. For /v0.x releases breaking changes can be made between minor versions. Once the product is released, it must be updated to be /v1 and our standard backwards compatibility rules are enforced.

Examples

  • https://api.nexmo.com/v0.2/dispatch
  • https://api.nexmo.com/v1/calls
  • https://api.nexmo.com/v3/media

Why did we choose this?

Beta

Discussed in #api-standards due to the messaging/workflows release.

Non-beta

Pre-existing standard