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.

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

Enter API version details

For each API that you register with Akamai, you can specify a version value and the location of the version value in incoming requests.

Optional: On the Register new API page, in the API version location field, select the location where the details about your API version are stored.
This can either be a base path (for example, /api/v1/users), query string (for example, /api/users?version=1), or header. You can either use a custom HTTP header to indicate the version (for example, API-Version: 1), or the Accept header to indicate the version together with the acceptable content-type (for example, Accept: application/vnd.mycompany.myapp-v2+xml).
Select API version location:

📘
You may use wildcards (*) to broaden the number of acceptable version values. For example, in the Accept header case, you may allow API consumers to send requests of any content type: application/*; version=1. In the base path case, you may allow all requests regardless of the version: api/v*/

If...	Then...
If you selected Base path for the API version location,	enter the version value in the Base path field. For example: `api/v1/`
If you selected Header for the API version location,	configure these fields: a. In the Header name field, enter the name of the HTTP header that includes the version details. For example: `API-Version` or `Accept`. b. In the API version field, enter the version value included in the HTTP header. For example: `1`. When you use the `Accept` header to indicate both the version and the acceptable content type, the value is usually longer and may look like one of the following examples: - `application/json; version=1` - `application/vnd.myapp.user.v1+json` - `application/vnd.myapp+xml;version=1 application/vnd`
If you selected Query parameter for the API version location,	configure these fields: a. In the Query param name field, enter the name of the query parameter that includes the version details. For example: `version` b. In the API version field, enter the version value included in the query parameter. For example: `1` (the full URL with the query parameter could look like this: `http://myapp.com/api/?version=1`)