API configuration version management
You can create multiple versions of a single API configuration. This feature helps you keep track of changes to your endpoints over time and lets you go back to previously active configurations easily. You can view and manage all configuration versions of an endpoint in the version history panel accessible from the API Definitions main page.
On the API Definitions main page, you can access the version history panel for an API configuration by clicking the ellipsis icon (...) associated with the API and selecting Manage versions.
Version history panel
Sorting criteria
The version management panel lets you sort API configuration versions by the following criteria:
- Version. A hyperlink with an API configuration version number. You can click the link to access the version's endpoint and resource configuration page.
- Description. General information about an API configuration version.
- Last modified. The date of the last modification of an API configuration version
- Modified by. The name of a user who last modified an API configuration version.
- Based on. Another version that this API configuration version is based on.
- Staging status. The activation status of an API configuration version in the Akamai staging environment.
- Production status. The activation status of an API configuration version in the Akamai production environment.
Staging and production statuses
Each API version has corresponding staging and production statuses:
Active. An API configuration version is active on the associated Akamai network.
Pending. An API configuration version's activation status change is being propagated to the associated Akamai network.
Deactivated. An API configuration version is not active on the associated Akamai network, but it was active at some point in the past.
Inactive. An API configuration version is not active on the associated Akamai network and it has never been activated.
Failed. An API configuration version activation or deactivation attempt has failed. This may be caused by a connectivity issue.
After a version fails to activate, it never can successfully activate. In this case, create a new version of the API configuration and activate that new one.
You can view more detailed information about every activation and deactivation of different API configuration versions by selecting the Activation history tab.
Actions
In the version history panel, you can click the ellipsis icon (...) next to an API configuration version and, depending on the activation status, do one of the actions presented in the following table.
| Active | Inactive | Deactivated | |
|---|---|---|---|
| View version | X | X | X |
| Edit version | X | ||
| Delete version | X | ||
| Activate version | X | X | |
| Deactivate version | X | ||
| Clone new version from <version_number> | X | X | X |
| Hide version | X | X |
You can also select any two versions of an API configuration and compare their parameters by clicking the Compare versions button.
After you hide inactive or deactivated versions, you can control whether they appear on the page by using the menu next to the Create new version button. The menu lets you show all versions, show only visible versions, or show only hidden versions.
Activation history
The activation history panel lets you view detailed information about each activation and deactivation of your API configuration versions.
You can access the activation history panel by selecting the Activation history tab in the version management panel of an API configuration.
Activation history panel
You can sort API activation and deactivation instances by the following criteria:
- Timestamp. The date and time of an activation/deactivation.
- Version. A hyperlink to a specific API version. You can click the link to access the version's endpoint and resource configuration page.
- Network. The network where an API version has been activated or deactivated; either Production or Staging.
- Activation notes. Additional information about an activation/deactivation instance entered by the user who performed the action.
- User. The name or email address of the user who activated or deactivated an API configuration version.
Activation statuses
Each activation or deactivation instance has a corresponding activation status. The following statuses are available:
- Activation successful. An API configuration version has been successfully activated.
- Activation triggered/Deactivation triggered. The activation or deactivation process of an API configuration version has been started and the change is being propagated to the Akamai network.
- Deactivated. An API configuration version has been deactivated either as a result of activating another version, or a direct user-initiated deactivation.
- Activation failed/Deactivation failed. An API configuration version activation or deactivation has failed. This may be caused by a connectivity issue.
After a version fails to activate, it never can successfully activate. In this case, create a new version of the API configuration and activate that new one.
Activate an API configuration version
You must activate the API configuration version that you set up in API Definitions to make your endpoint, resource, and delivery configurations effective. You can activate the API configuration version in the staging or production environment. The staging environment lets you test your API settings without impact to the production network. The production environment is where your real API traffic flows.
API
You can also complete this task by using the API Endpoints API. Run the Activate a version operation. Learn more about Akamai's APIs.
Before you begin, ensure that the property associated with your API configuration is active on the network where you want to perform the activation.
Ensure that you are aware of the following possible implications of activating an API configuration version:
- If another version of the API configuration is already active on the specified network, that version becomes automatically deactivated and the newly activated version takes its place.
- If an active version of another API configuration has the same API URLs (base path + hostname) as the version you activate, the system automatically deactivates the version with conflicting URLs, creates a new version within the impacted API configuration, migrates the non-conflicting hostnames and other API details to the new version, and activates the new version.
-
On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API whose configuration version you want to activate.
-
From the menu, select Activate API.
-
In the Activate API window, from the Activate version menu, select the API configuration version that you want to activate.
-
In the Activate API version on area, select the network where you want to activate the API.
To ensure that your settings work as expected, first activate the API configuration version in the staging environment and test the configuration before activating in the production environment.
-
Optional: In the Notes field, enter additional information about the activation.
You can use this field to document changes for future reference. -
Optional: In the Notification emails field, select or enter at least one email address to receive a notification when the API configuration version becomes active.
-
Optional: Ensure that the property associated with your API configuration is active on the selected network. Click Check property's status.
If at least one property associated with your API configuration is inactive on the selected network, the traffic will not flow on that network after you activate the API configuration version. For guidance on activating properties, see either Activate API Gateway in the staging environment or Activate API Gateway in the production environment.
-
Click Activate.
The activation of the API configuration version starts and should take approximately 20 minutes for the staging, and 30 minutes for the production network. You can track progress by monitoring the pending icon () next to the affected API configuration version.
When the process completes, a success message appears at the top of the page and the activated icon ( replaces the pending icon ().
Clone an API configuration version
If you want to create a new version of a registered API, you can do so by cloning an already existing version. After completing this action, you go directly to a pre-populated configuration page where you can modify selected fields without the necessity of entering all API details from the beginning.
API
You can also complete this task by using the API Endpoints API. Run the Clone a version operation. Learn more about Akamai's APIs.
-
On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API whose configuration version you want to clone.
-
From the menu, select Manage versions.
-
In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to clone.
-
From the menu, select Clone new version from <version_number>.
-
In the confirmation window that opens, click Clone.
The cloned API configuration version opens on the endpoint and resource configuration page and you can modify the existing settings. -
Modify the API base path or API hostnames to ensure that API endpoint URLs are unique.
-
If you do not want to make any additional changes to the cloned API configuration version, click Save.
Group clone and activate to implement evasive URL request matching
If you turned on evasive URL request matching (beta) in your web application firewall solution (learn more in App & API Protector, Kona Site Defender, or Web Application Protector help), you must version and activate any APIs which contain endpoints you want covered. Any APIs you don't version and activate—even if they're covered by a security configuration or security policy in which you turned matching on—can't use this feature.
-
From the control center menu, select CDN > API Definitions.
To help you version and activate the APIs affected by evasive URL request matching, the Registered APIs list that opens shows a message reminding you to clone and activate these APIs.
-
Click this message's Group clone and activate button.
-
Select all the APIs you want and click Group clone and activate.
Evasive URL request matching won't work if you use any of the following characters as part of your base path or resource path:
! $ ' ( ) + , @
Compare API configuration versions
The version comparator feature included in API Gateway lets you view differences and similarities between two selected versions of one registered API configuration. By comparing API configuration versions, you can easily identify configuration changes that altered your API traffic and understand how your settings evolved over time.
-
On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration whose versions you want to compare.
-
From the menu, select Manage versions.
-
In the Version history panel, select the two versions that you want to compare. Click Compare versions.
In the Compare versions window, you can compare API endpoint properties, security settings, JWT validation,
CORS, caching, and other properties associated with your API configuration versions. You can also see how
specific resources within your API configuration changed over time. For information about different properties,
see the following sections:- API base properties
- For those who also use a web application firewall product only: API request body and resource constraints
- JWT validation properties
- CORS properties
- Caching properties
- Other properties
- Resource properties
- For web application firewall customers only: Parameter properties
- For Bot Manager customers only: Purposes properties
To enter fullscreen mode, click
.
-
Optional: If you want to see only the differences between two configuration versions, ensure the Show only differences check box is selected.
The differences are divided into three types:- Removed. Items that have been removed from the version. Marked in red.
- Changed. Items whose value has been changed. Marked in yellow.
- Added. Items that have been added to the version. Marked in green.
-
Optional: To compare properties of other configuration versions, from the menus in the top-left corner, select the versions you want to view. Click Compare.
-
When you finish comparing versions, close the Compare versions window.
Learn more
API base properties
The following table lists API endpoint definition properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| API name | The name of an API configuration. |
| Base path | The base path on which an API serves content. |
| API hostnames | The hostnames associated with an API. |
| API description | The description of an API. |
| Updated by | The name of the user who performed the most recent update to an API configuration version. |
| Date updated | The date and time of the most recent update to an API configuration version in UTC format. |
| Allowed content types | The content types that an API accepts; either JSON, XML, or both. |
| URL scheme | The protocol to which an API may respond; either HTTP, HTTPS, or both. |
| Security scheme | Whether an API configuration version uses API keys for security. |
| API key location | The location of the API key in incoming requests, either a cookie, header, or query parameter. |
| API key name | The name of the header, query parameter, or cookie where you located the API key. |
API request body and resource constraints
The following table lists the API security properties that you can view when comparing two API configuration versions.
These properties are available for web application firewall customers only. To learn more about API request body and resource constraints, see the user guide for your web application firewall product, like App & API Protector.
| Property | Description |
|---|---|
| Max value for any integer value | The maximum allowed value of any integer included in the API request body. |
| Max number of JSON members or XML elements | The maximum number of JSON keys or XML elements allowed in the API request body. |
| Enforced as allow lists in Akamai web application firewall product policy | Whether any request body and resource constraints are enforced as allow lists in your web application firewall product. |
| Max nesting depth | The maximum number of nested JSON objects or XML elements allowed in the API request body. |
| Max length for any string value | The maximum allowed string value length in the API request body. |
| Max length for any JSON member or XML element | The maximum allowed JSON or XML element length in the API request body. |
| Max body size | The maximum allowed API request body size in bytes. |
JWT validation properties
The following table lists the JWT validation properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| JWT enabled | Whether JWT validation is enabled for an API configuration version. |
| JWT location | The location of the JWT in incoming requests. |
| JWT name | The name of the JWT location. |
| Clock skew amount | The allowed time difference (in seconds) between the server and client clocks when validating the exp and nbf JWT claims. |
| Claim value | The value of a JWT claim. |
| Claim required | Whether the inclusion of a JWT claim in a request is mandatory. |
| Claim regex | Whether the value of a JWT claim should be parsed as a regular expression. |
| Claim validation | Whether the value of a JWT claim should be validated. |
| RSA public key name | The name of the RSA public key. |
| RSA public key value | The value of the RSA public key. |
CORS properties
The following table lists the CORS properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| CORS enabled | Whether CORS is enabled for an API configuration version. |
| Allowed credentials | Whether an API version accepts credentialed HTTP requests. |
| Preflight max age | The maximum time for caching responses to preflight requests indicated in the Access-Control-Max-Age response header. |
| Allowed origins | The hostnames allowed via the Access-Control-Allow-Origin response header. |
| Allowed methods | The methods allowed via the Access-Control-Allow-Methods response header. |
| Allowed headers | The HTTP headers allowed via the Access-Control-Allow-Headers response header. |
| Exposed headers | The HTTP headers exposed via the 1Access-Control-Expose-Headers` response header. |
Caching properties
The following table lists the caching properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| Caching enabled | Whether caching is enabled for an API configuration version. |
| Caching option | The option for passing cached content. |
| Max age of cached content | The maximum time for caching content. |
| Max age time unit | The time unit for the Max age parameter. |
| Serving stale objects on origin error | Whether expired objects should be served when revalidation with the origin server is not possible. |
| Error caching enabled | Whether caching of error responses is enabled for an API version. |
| Cache lifetime | The maximum lifetime of objects cached downstream. |
| Headers sent downstream | The type of headers that are sent downstream. |
| Private cache | Whether the HTTP responses are stored in a private cache. |
| Preserve stale objects | Whether stale error responses should be preserved when revalidation with the origin server is not possible. |
Other properties
The following table lists additional properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| GZIP compression | The type of GZIP compression configuration selected for an API configuration version. Either Always, Same as origin, or Never. |
| API privacy | Whether API keys govern access to an API configuration version. |
Resource properties
The following table lists resource properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| Resource name | The name of a resource. |
| Resource path | The path relative to the API hostnames on which the resource resides. |
| Resource notes | The description of a resource. |
| Resource method | The method associated with a resource. |
Parameter properties
The following table lists the parameter properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| Parameter type | The type of a parameter. |
| Parameter required | Whether a parameter is mandatory. |
| Parameter location | The location of a parameter. |
| Parameter notes | The description of a parameter. |
| Parameter array restriction | For array parameters, the maximum number of elements in an array. |
| Minimum range | For numerical parameters, the minimum value of a parameter. |
| Maximum range | For numerical parameters, the maximum value of a parameter. |
| Minimum string length | For string parameters, the minimum length of a parameter. |
| Maximum string length | For string parameters, the maximum length of a parameter. |
Operation properties
(formerly purpose properties)The following table lists purposes properties that you can view when comparing two API configuration versions.
| Property | Description |
|---|---|
| Operation purpose | The task an operation (transactional endpoint) serves, like login, for example. |
| Operation name | The name of the operation. |
| Method | The HTTP method uses. |
| Username parameter | The location of the username parameter for operations of Login type. |
| Parameter exists | Whether a parameter must exist. |
| Parameter match value | Whether a parameter must match a certain value. |
Deactivate API configuration versions
You can deactivate an API configuration version together with all its endpoint, resource, security, and delivery settings in staging, production, or both environments. Two API configuration versions cannot be active in the same environment simultaneously. The following deactivation steps only affect your API traffic. After you complete this task, the properties associated with your API configuration remain active on the Akamai network.
API
You can also complete this task by using the API Endpoints API. Run the Deactivate a version operation. Learn more about Akamai's APIs.
-
On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration whose version you want to deactivate.
-
From the menu, select Deactivate API.
-
In the Deactivate API window, in the Deactivate API on area, select the environment and version for the deactivation.
You can deactivate two versions at a time, on the staging and production networks. -
Optional: In the Notes field, enter additional information about the deactivation.
You can use this field to document changes for future reference. -
Optional: In the Notification emails field, select or enter at least one email address to receive a notification when the deactivation completes.
-
Click Deactivate.
The deactivation of the API configuration version starts and should take approximately 20 minutes for the staging, and 30 minutes for the production network. You can track progress by monitoring the pending icon () next to the affected API configuration version.
When the process completes, a success message appears at the top of the page and the deactivated icon () replaces the pending icon ().
Delete an API configuration version
You can delete an inactive API configuration version that has never been activated in the staging or production environment.
API
You can also complete this task by using the API Endpoints API. Run the Delete a version operation. Learn more about Akamai's APIs.
-
On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration whose version you want to delete.
-
From the menu, select Manage versions.
-
In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to delete.
-
From the menu, select Delete version.
-
In the Delete API version window, click Delete.
The version disappears from the versions list.
Edit an API configuration version
You can edit an inactive API configuration version at any point after registering your API with Akamai. An inactive API configuration version is one that has never been activated on the Akamai network.
API
You can also complete this task by using the API Endpoints API. Run the Edit a version operation. Learn more about Akamai's APIs.
-
On the API Definitions page, click the ellipsis icon (...) next to an API configuration whose version you want to edit.
-
From the menu, select Manage versions.
-
In the Version history panel, click the inactive API configuration version that you want to edit.
The API registration page opens. You can edit information about your API, import a new API definition file, add resources, and modify security and delivery settings. -
Edit the API configuration version and click Save.
Hide an API configuration version
You can hide an inactive or deactivated API configuration version so that it no longer appears in the Version history panel. You cannot activate or delete hidden API configuration versions.
API
You can also complete this task by using the API Endpoints API. Run the Hide a version and Show a version operations. Learn more about Akamai's APIs.
-
On the API Definitions page, click the ellipsis icon (...) next to an API configuration whose version you want to hide.
-
From the menu, select Manage versions.
-
In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to hide.
-
From the menu, select Hide version.
The version disappears from the versions list. You can control whether hidden versions appear on the list by using the drop-down menu next to the Create new version button. You can reveal a hidden version permanently by clicking its corresponding Show link in the Action column.
Updated 3 months ago