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
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.