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.

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.

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

  2. From the menu, select Activate API.

  3. In the Activate API window, from the Activate version menu, select the API configuration version that you want to activate.

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

  1. Optional: In the Notes field, enter additional information about the activation.
    You can use this field to document changes for future reference.

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

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

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

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

  2. From the menu, select Manage versions.

  3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to clone.

  4. From the menu, select Clone new version from <version_number>.

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

  6. Modify the API base path or API hostnames to ensure that API endpoint URLs are unique.

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

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

  2. Click this message's Group clone and activate button.

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

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

  2. From the menu, select Manage versions.

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

👍

To enter fullscreen mode, click .

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

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

Purposes properties

The following table lists purposes properties that you can view when comparing two API configuration versions.

Property

Description

Purpose type

The type of a resource purpose.

Purpose name

The name of a resource purpose configuration.

Purpose method

The HTTP method used in combination with a resource.

Username parameter

The location of the username parameter for resource purposes 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.

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

  2. From the menu, select Deactivate API.

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

  4. Optional: In the Notes field, enter additional information about the deactivation.
    You can use this field to document changes for future reference.

  5. Optional: In the Notification emails field, select or enter at least one email address to receive a notification when the deactivation completes.

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

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

  2. From the menu, select Manage versions.

  3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to delete.

  4. From the menu, select Delete version.

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

  1. On the API Definitions page, click the ellipsis icon (...) next to an API configuration whose version you want to edit.

  2. From the menu, select Manage versions.

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

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

  1. On the API Definitions page, click the ellipsis icon (...) next to an API configuration whose version you want to hide.

  2. From the menu, select Manage versions.

  3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version that you want to hide.

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


Did this page help you?