API versioning

Versioning is one of the most important aspects of maintaining an API. It prevents invalid requests from hitting outdated resources and keeps your API both forward and backward compatible for a period of time.

APIs must constantly evolve to remain competitive and meet API consumers’ growing needs. Changes to an API may be divided into two categories: breaking and non-breaking.

Some examples of safe or backward-compatible changes include:

  • Adding a new resource
  • Adding a new event type
  • Adding new properties to responses
  • Changing the order of properties
  • Adding optional parameters to existing methods

These changes ensure that API clients can continue accessing API resources and expect familiar responses.

Conversely, any change that disrupts the backwards compatibility of an API is considered a breaking change. For example: a developer modifies the data model such that a cost member changes to an integer from a string. When you introduce a breaking change to your API, you should create a new version of your API.

API Gateway lets you specify a version for each API that you register. You can do this on the API registration page, in the API endpoint section. In API Definitions, you enter the location of the API version value in an incoming request and the expected version value. The version value differs depending on the API version location you select. The location might be a base path, query parameter, or header.

Note: In API Definitions you can also create versions of API configurations registered in API Gateway. These two concepts are unrelated, and should be considered independent features. For details on API configuration versioning, see API configuration version management.