loading

Akamai Cloud Embed API v2

Add customers to access your unique Akamai Cloud Embed CDN instance, and manage policies of rules and behaviors specific to each customer.

Learn more:


Overview

As an Akamai cloud partner, you can use the Akamai Cloud Embed (ACE) API to provide Content Delivery Network (CDN) features to your cloud customers, known as “subcustomers.”

You can configure CDN features per domain and give subcustomers the ability to buy, configure, and monitor Akamai’s CDN services directly through your portal.

In most cases, once you create one or more base configurations to support your business needs, you can use this API to support hundreds of thousands of subcustomers per base configuration.

To use this API and its core delivery, download, and video streaming capabilities, you need to add ACE to your contract. To use the acceleration features, you have to sign up for Integrated Cloud Accelerator (ICA).

NOTE: The former name of Akamai Cloud Embed was Wholesale Delivery.

Get started

To configure this API for the first time:

  • Contact Akamai to enable ACE for your account. If you want acceleration features, you also need to add ICA.

  • If your subcustomers support both HTTP and HTTPS traffic, contact Akamai to create a secure ACE base configuration and provision the necessary certificates. Akamai recommends this configuration for ACE. You can create this configuration yourself, using Property Manager in Akamai Control Center.

  • If your subcustomers only support HTTP traffic, contact Akamai to request a multi-domain edge hostname and create an InstantConfig property. A multi-domain edge hostname lets you use a single hostname to represent multiple web assets.

  • Create an origin hostname. You need to create a hostname to identify a default origin server that is separate from your subcustomer cloud origins.

  • Create an error page. Once you create a hostname to identify a default origin server, configure this default origin to serve an error page when subcustomers don’t configure their domain correctly.

  • Determine the method to use to create subcustomer IDs. Each customer in your billing system who uses your ACE implementation needs this ID. You can use any method to generate IDs as long as the IDs are unique. Akamai rolls all traffic for a particular subcustomer into this ID for billing.

  • Add the Sub-Customer Enablement behavior to your base configuration via Property Manager in Akamai Control Center. Once added, you need to decide which ACE features you want to offer to your subcustomers, and enable them accordingly. Your decisions determine the structure of your policy JSON going forward. (Your policy JSON is made up of rules that include both match criteria and behaviors for use with that specific subcustomer.)

  • If you’re using ICA, make sure you enable the Dynamic Web Content option in the Sub-Customer Enablement behavior.

  • If you’re using a non-secure (HTTP), Multi-Domain Edge Hostname, enable the InstantConfig behavior in your base configuration via Property Manager. InstantConfig lets you associate multiple web assets to a single property without adding each hostname to the base configuration.

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Wholesale Delivery, and set the access level to READ-WRITE.

Interactions with other Akamai APIs

You can use the ACE API in conjunction with the following Akamai APIs:

  • Billing Center. This provides access to CSV-based contract usage data for accounts you can access. We provide separate reports for ACE and Integrated Cloud Acceleration (ICA), per billing period. The ACE report lists subcustomer usage (hits and bytes) by geography. The ICA report contains billing data for subcustomers that used ICA, without reference to geography.

  • Media Delivery Reports. Use this to review traffic, usage, and quality metrics for all of the products in the Media Delivery suite, including ACE. Currently, this API combines ACE and ICA data: If a given operation served both ACE and ICA traffic during the selected time period, the report doesn’t differentiate between the two.

  • Property Manager API. You can use the Property Manager API to create and update a base configuration for ACE. However, you typically only need one base configuration. For ease of use, we recommend that you use Property Manager via Control Center.

Concepts

  • Cloud partners. Akamai resellers or partners who provide delivery services to their customers. You, as a user of this API, are a cloud partner, also referred to simply as “partner” throughout this documentation.

  • Subcustomers. A cloud partner’s customers are subcustomers. Akamai does not assign individual Content Provider (CP) codes to subcustomers even though their traffic is sent over the Akamai platform. As a Cloud Partner you have access to usage detail reports for each of your subcustomers, based on the subcustomer IDs you provide Akamai.

  • Subcustomer ID. This is a unique ID for each subcustomer within your own billing systems. All traffic for a particular subcustomer is rolled up by this ID for billing purposes.

  • Base configuration. An Akamai delivery configuration that includes all of the common rules for processing end-user requests. You use the Property Manager API or GUI application to configure properties used for both ACE and ICA.

  • Sub-Customer Enablement behavior. In Property Manager, the subCustomer behavior controls which individual ACE and ICA features you can use to handle your subcustomers’ traffic. You can set up this behavior to provide access to all available features, or you can select a subset of features to define different classes of service.

  • Content Characteristics-Dynamic Web Content behavior. Include this behavior if you want to enable specific ICA optimizations for your subcustomers.

  • InstantConfig behavior. If your subcustomers specifically send HTTP traffic, you have to add the instantConfig behavior to your property. This behavior, also known as Multi-Domain Configuration, lets you to associate multiple web assets to a single property without adding each hostname separately. It applies property settings to all incoming hostnames based on a DNS lookup.

  • Policy. Policies determine how Akamai edge servers handle a given subcustomer’s requests. A single policy is bound to a hostname. Your policy JSON is made up of rules, which contain both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Make rules unique within a policy: they can’t have identical sets of matches. A policy can also contain up to 100 behaviors.

  • Policy rules. Rules include both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Within a rule you can use each match type and each behavior once. Also, no one rule can contain both a whitelist and blacklist behavior of a given type. For example, you can add an IP whitelist and a referrer blacklist to a rule, but you can’t have both an IP whitelist and an IP blacklist in the same rule. ACE applies rules from top to bottom, so ensure you list them from least restrictive to most restrictive. For example, you would list a match on url-wildcard value /* first because it would apply to all requests, where /images/* would only apply to a subset of requests.

  • Policy matches. Within a rule, a match defines which subcustomer requests receive the behaviors within the rule. If a match condition for a rule is met, ACE applies the behaviors set in a rule. When constructing the matches array in a rule, the type of data you enter depends on the type of match. For example, if you use the query string match, you have to enter the exact string and keep case sensitivity in mind. If you use the url-scheme match, you enter either HTTP or HTTPS. Within a match, you cannot repeat entries in the value string.

  • Policy behaviors. Like Property Manager, the ACE API uses behaviors to encapsulate settings to customize a configuration. Behaviors are a part of a policy’s rules. A rule can have many behaviors or only one. For the ACE API, you group rules into policies. You can have a maximum of 100 behaviors in a subcustomer policy. ACE rejects policies exceeding 100 behaviors upon submission. Within a behavior, you cannot repeat entries in the value string.

Resources

The Akamai Cloud Embed API allows you as our “partner” to manage the Content Delivery Network (CDN) features available to your customers (“subcustomers”) when using Akamai Cloud Embed or Integrated Cloud Acceleration (ICA). With this API, you can create and manage subcustomer policies and IDs.

Follow this basic workflow to create a subcustomer ID and policy:

  1. Complete the prerequisites in Get started.

  2. If not completed already, use Property Manager in Akamai Control Center to create a “base configuration,” and ensure that you configure the Sub-Customer Enablement behavior to meet your needs. This configuration and behavior determine baseline settings for use. (It serves as a “limiter.” It states what settings can and can’t be used in a policy for all subcustomers assigned to the configuration).

  3. Run the Add a new subcustomer operation to apply and register a “subcustomer ID” for each of your customers.

  4. Run the Create or update a policy operation for each subcustomer ID you need to add to your base configuration. Set up the policy with individual rules and behaviors that you want applied when ACE receives a request for that subcustomer’s content.

  5. Test the end-to-end CDN functionality with each subcustomer. You should use a test domain to verify both the functionality and the configuration.

  6. For the final step to go live, change applicable DNS to switch Cloud Partner websites to the Akamai platform.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Subcustomer  
List all subcustomers GET /partner-api/v2/network/{network}/properties/{propertyId}/customers
Get a subcustomer GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Add a new subcustomer PUT /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Remove a subcustomer DELETE /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Property  
List all sub-properties for a base configuration GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties
List all subcustomer domains GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties
Policy  
Get a policy GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Create or update a policy PUT /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Delete a policy DELETE /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Get policy history GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history
Get latest active policy GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/active

List all subcustomers

Returns a list of all subcustomers assigned to the selected base configuration (propertyId).

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/customers

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration.

Status 200 application/json

Object type: SubCustomer

Download schema: subcustomerID-get-all-for-config.json

Response body:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers.

  4. Review the list of subcustomers and their geographies returned in the SubCustomer response.

Get a subcustomer

Returns policy information for the selected subcustomer and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/customers/SC12345

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Object type: SubCustomer

Download schema: subcustomerID-add-get.json

Response body:

{
    "geo": "FR"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List customers operation and store the customer value, which corresponds to the subcustomerId URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}.

Add a new subcustomer

Add a new subcustomer ID to the selected base configuration (propertyId).

PUT /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/customers/SC12345

Content-Type: application/json

Object type: SubCustomer

Download schema: subcustomerID-add-get.json

Request body:

{
    "geo": "FR"
}
Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Object type: SubCustomer

Download schema: subcustomerID-add-get.json

Response body:

{
    "geo": "FR"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. You need to provide a unique ID for the subcustomer (subcustomerId). As the cloud partner, it’s up to you to determine a method to create these IDs and associate them with each subcustomer. The ID can contain up to 50 alphanumeric, dot or dash characters.

  4. Make a PUT request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}. You also need to include the subcustomer’s geo (geographic region) in a PUT request body. Use the valid two letter country designation (for example, US for United States or BR for Brazil).

  5. Verify that the geo value returned in the response is accurate for the subcustomer you added.

Remove a subcustomer

Remove a specific subcustomer using its unique subcustomerId

DELETE /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/customers/SC12345

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Download schema: subcustomerID-delete.json

Response body:

{
    "description": "The subcustomer for property_id '251922' and subcustomer_id '0004-propertyfolks' was successfully deleted.",
    "message": "Successfully deleted"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List all subcustomers operation and store the customerID value, that applies to the applicable subcustomer. Use this as the subcustomerId URL parameter for this operation.

  4. Make a DELETE request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}.

  5. Review the Message response returned to verify the deletion was successful.

List all sub-properties for a base configuration

Returns all of the domains (subPropertyID values) for subcustomers assigned to a selected base configuration (propertyId) and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.

Status 200 application/json

Object type: SubProperty

Download schema: subproperty-get-all-for-property.json

Response body:

[
    {
        "subPropertyID": "www.example.com",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.biz",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.com.net",
        "customerID": "def-456"
    },
    {
        "subPropertyID": "www.example.com.co.uk",
        "customerID": "def-456"
    }
]
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties.

List all subcustomer domains

Returns domain-specific information for the selected subcustomer domain (subPropertyID) and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/customers/SC12345/sub-properties

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Object type: SubProperty

Download schema: subproperty-get-all-for-subcustomer.json

Response body:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List customers operation and store the customer value, which corresponds to the subcustomerId URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties.

Get a policy

Returns the policy for the selected subcustomer domain, base configuration (propertyId), and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties/www.example.com/policy

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Object type: Policy

Download schema: policy-rule.json

Response body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "/",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "type": "-",
                    "value": "-"
                },
                {
                    "name": "content-refresh",
                    "type": "fixed",
                    "value": "1m"
                }
            ]
        }
    ],
    "activationStatus": "ACTIVE"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. Use this as the domainName URL parameter for this operation.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy.

  5. Review the rule information returned in the Policy response.

Create or update a policy

Create a new subcustomer policy or update an existing one.

PUT /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties/www.example.com/policy

Headers:

X-Customer-ID: 100-example.com
X-Custom-Metadata: 100

Content-Type: application/json

Object type: Policy

Download schema: policy-rule.json

Request body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "/",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "type": "-",
                    "value": "-"
                },
                {
                    "name": "content-refresh",
                    "type": "fixed",
                    "value": "1m"
                }
            ]
        }
    ],
    "activationStatus": "ACTIVE"
}
Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Object type: Policy

Download schema: policy-rule.json

Response body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "/",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "type": "-",
                    "value": "-"
                },
                {
                    "name": "content-refresh",
                    "type": "fixed",
                    "value": "1m"
                }
            ]
        }
    ],
    "activationStatus": "ACTIVE"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. Use this as the domainName URL parameter for this operation.

  4. Include a valid, registered subcustomer ID as the X-Customer-ID header. You can also optionally specify a string up to 50 characters in length to serve as the X-Custom-Metadata header, for use in billing and reporting.

  5. Make a PUT request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy. Include a properly formatted request body with rules that consist of proper match criteria, and the behaviors that you want applied when a request for the subcustomer’s content meets that criteria.

  6. Review the information returned in the Policy response.

Delete a policy

Deletes the currently active policy file for the selected subcustomer domain and activation network.

DELETE /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties/www.example.com/policy

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Download schema: policy-delete.json

Response body:

{
    "message": "Successfully deleted",
    "description": "The policy was successfully deleted.",
    "successInstanceId": "a123bcedfg45"
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. Use this as the domainName URL parameter for this operation.

  4. Make a DELETE request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy.

  5. Review the Message response returned to verify the deletion was successful.

Get policy history

Returns policy change information for the selected subcustomer domain, base configuration (propertyId), and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties/www.example.com/policy/history

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Object type: Policy

Download schema: policy-rule-history.json

Response body:

{
    "policy": {
        "rules": [
            {
                "behaviors": [
                    {
                        "name": "origin",
                        "params": {
                            "cacheKeyType": "digital_property",
                            "cacheKeyValue": "-",
                            "digitalProperty": "sportsguys.wsdtest.akalab.com",
                            "hostHeaderType": "digital_property",
                            "hostHeaderValue": "-",
                            "originDomain": "sportsguys.wsdtest.akalab.com.s3-website-us-west-1.amazonaws.com"
                        },
                        "value": "-"
                    }
                ],
                "matches": [
                    {
                        "name": "http-method",
                        "value": "GET"
                    }
                ]
            },
            {
                "behaviors": [
                    {
                        "name": "caching",
                        "type": "fixed",
                        "value": "1h"
                    }
                ],
                "matches": [
                    {
                        "name": "url-extension",
                        "value": "jpg"
                    }
                ]
            },
            {
                "behaviors": [
                    {
                        "name": "caching",
                        "type": "fixed",
                        "value": "1d"
                    }
                ],
                "matches": [
                    {
                        "name": "url-extension",
                        "value": "mp4"
                    }
                ]
            }
        ]
    },
    "update_timestamp": 1440722458,
    "version": 1
}
  1. Determine which network you want to gather information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId assigned to the applicable base configuration.

  3. Run the List all sub-properties for a property ID operation and store the appropriate value from the subPropertyIDs array, which corresponds to the domainName URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history.

  5. Review the rule information returned in the Policy response.

The response includes up to 100 of the most recent versions, not including the current version. If there are more than 100 versions of a policy, ACE discards the oldest policy. (For example, version 101 replaces version 1.)

Get latest active policy

Returns the latest activated version of the policy, one with an activationStatus of ACTIVE. If no active version exists, the API returns a 404 error.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/active

Sample: /partner-api/v2/network/production/properties/a123bcdefg45/sub-properties/www.example.com/policy/active

Parameter Type Sample Description
URL path parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String a123bcdefg45 The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Object type: Policy

Download schema: policy-rule.json

Response body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "/",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "type": "-",
                    "value": "-"
                },
                {
                    "name": "content-refresh",
                    "type": "fixed",
                    "value": "1m"
                }
            ]
        }
    ],
    "activationStatus": "ACTIVE"
}

Data

This section shows you the data model for the Akamai Cloud Embed API. The main “{Object}” sections reveal an example of the JSON returned for a GET call. The “{Object} Members” sub-sections illustrate elements that are required or optional, based on the call method. For example, “required” indicates the element must be used in the request body for a PUT method call, and it is always included in the response for a GET call.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

SubCustomer

Allows you to add or update a subcustomer.

Download schema: subcustomerID-add-get.json

Sample GET response:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]

SubCustomer members

Member Type Required Description
SubCustomer: Allows you to add or update a subcustomer.
geo String The geographic location of the subcustomer.

SubProperty

Lists ID, domain, and geographic information for a subproperty, which is the subcustomer’s domain.

Download schema: subproperty-get-all-for-subcustomer.json

Sample GET response:

[
    {
        "subPropertyID": "www.example.com",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.biz",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.com.net",
        "customerID": "def-456"
    },
    {
        "subPropertyID": "www.example.com.co.uk",
        "customerID": "def-456"
    }
]

SubProperty members

Member Type Required Description
SubProperty: Lists ID, domain, and geographic information for a subproperty, which is the subcustomer’s domain.
customerID String The ID of the customer assigned to the subproperty.
geo String The geographic location of the subcustomer.
subPropertyID String A unique string representing the subcustomer’s domain.

Policy

Encapsulates rules consisting of match criteria and resulting behavior settings Akamai Cloud Embed (ACE) applies for a specific subcustomer.

Download schema: policy-rule.json, policy-rule-history.json

Sample GET response:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "/",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "type": "-",
                    "value": "-"
                },
                {
                    "name": "content-refresh",
                    "type": "fixed",
                    "value": "1m"
                }
            ]
        }
    ],
    "activationStatus": "ACTIVE"
}

Sample GET history response:

{
    "policy": {
        "rules": [
            {
                "behaviors": [
                    {
                        "name": "origin",
                        "params": {
                            "cacheKeyType": "digital_property",
                            "cacheKeyValue": "-",
                            "digitalProperty": "sportsguys.wsdtest.akalab.com",
                            "hostHeaderType": "digital_property",
                            "hostHeaderValue": "-",
                            "originDomain": "sportsguys.wsdtest.akalab.com.s3-website-us-west-1.amazonaws.com"
                        },
                        "value": "-"
                    }
                ],
                "matches": [
                    {
                        "name": "http-method",
                        "value": "GET"
                    }
                ]
            },
            {
                "behaviors": [
                    {
                        "name": "caching",
                        "type": "fixed",
                        "value": "1h"
                    }
                ],
                "matches": [
                    {
                        "name": "url-extension",
                        "value": "jpg"
                    }
                ]
            },
            {
                "behaviors": [
                    {
                        "name": "caching",
                        "type": "fixed",
                        "value": "1d"
                    }
                ],
                "matches": [
                    {
                        "name": "url-extension",
                        "value": "mp4"
                    }
                ]
            }
        ]
    },
    "update_timestamp": 1440722458,
    "version": 1
}

Policy members

Member Type PUT GET Description
Policy: Encapsulates rules consisting of match criteria and resulting behavior settings Akamai Cloud Embed (ACE) applies for a specific subcustomer.
activationStatus Enumeration The current propagation status of the policy. This can be PROPAGATING for a policy that is still being processed, ACTIVE for a policy that has successfully completed propagation, or ACTIVATION_FAILED for a policy that encountered an error during propagation. Get the policy to check its configuration and update the policy to resubmit it for propagation.
rules Policy.rules[] The set of matches and behaviors for this subcustomer policy.
Policy.rules[]: The set of matches and behaviors for this subcustomer policy.
behaviors Policy.rules[].behaviors[] The behaviors to apply to requests that meet the match criteria set in this policy.
matches Policy.rules[].matches[] The criteria that identify which requests to process. When a request matches the criteria, ACE applies the behaviors to the request.
Policy.rules[].behaviors[]: The behaviors to apply to requests that meet the match criteria set in this policy.
name Enumeration The specific behavior you want to apply to incoming requests that meet the associated match criteria.
params Object The set of options that determine how the behavior operates.
type String The format to use for the value element.
value String The values to use for the selected behavior.
Policy.rules[].matches[]: The criteria that identify which requests to process. When a request matches the criteria, ACE applies the behaviors to the request.
name Enumeration The specific match criteria that must be met to apply the behaviors you define.
negated Boolean If set to true, ACE applies the behaviors set in this rule when an incoming request does not meet the match criteria.
value String The value to match.

Matches and Behaviors

A match defines the criteria to be met in a request for subcustomer content in order to apply the behaviors set in a rule.


Behaviors determine the settings ACE applies to the delivery of subcustomer content. Akamai Cloud Embed (ACE) applies a behavior’s settings when a request that meets the rule’s match criteria is received for a subcustomer’s content.

client-ip

Include this to match using the IP address assigned to the requesting client. You can specify individual IP addresses, or CIDR blocks (that express a range of addresses).

Download schema: client-ip-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "client-ip",
            "value": "-",
            "params": {
                "ipOrCidrList": [
                    "1.2.3.4",
                    "5.6.7.8",
                    "192.168.100.14/24",
                    "2001:db8:abcd:8000::/50"
                ],
                "source": "both",
                "ipFromHeader": "all"
            },
            "negated": true
        }
    ],
    "behaviors": []
}

client-ip members

Member Type Required Description
client-ip: Include this to match using the IP address assigned to the requesting client. You can specify individual IP addresses, or CIDR blocks (that express a range of addresses).
name Enumeration Enter client-ip to match based on the requesting client’s IP address.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
params client-ip.params[] Specifies each set of addresses along with criteria to match them.
value String All match criteria require the value member, but client-ip does not use one. Specify a dash for this member (-).
client-ip.params[]: Specifies each set of addresses along with criteria to match them.
ipFromHeader Enumeration When matching the X-Forwarded-For header, specifies which IP address to match in the list, either the first IP address, or all to match any.
ipOrCidrList Array Enter one or more specific IP addresses or CIDR blocks of IP addresses. If a requesting client is assigned to one of these IP addresses, the behaviors set in this policy are applied. For example, ["1.2.3.4", "5.6.7.8", "192.168.100.14/24", "2001:db8:abcd:8000::/50"].
source Enumeration Specifies where to find the IP address, either connectingIp for the requesting client’s IP address, headers for the X-Forwarded-For header, or both to match either location.

Include this match to define specific cookie names for use when matching on an incoming request.

Download schema: cookie-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "cookie",
            "value": "cookie-name cookie-value1 cookie-value2",
            "negated": true
        }
    ],
    "behaviors": []
}

cookie members

Member Type Required Description
cookie: Include this match to define specific cookie names for use when matching on an incoming request.
name Enumeration Enter cookie to use cookie names when matching on the incoming request.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Specifies the case-insensitive cookie name to match on. You can follow the cookie name with a space-delimited list of cookie values to match against, all of which are case-sensitive. Cookie name and cookie values do not support white spaces. Currently, the + ! ( ) [ ] { } characters are not supported, even though they are normally supported for use in cookies. For example, cookiename cookievalue1 cookievalue2.

geography

Use this match to test the requesting client’s location, either by continent, country, region, or designated market area (DMA). Each subcustomer policy can include up to ten geography matches.

Download schema: geography-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "geography",
            "value": "-",
            "params": {
                "continent": [
                    "AS",
                    "EU"
                ],
                "country": [
                    "IN",
                    "CA"
                ],
                "region": [
                    "US:CA",
                    "US:TX"
                ],
                "dma": [
                    500,
                    501,
                    502
                ],
                "source": "both",
                "ipFromHeader": "first"
            }
        }
    ],
    "behaviors": []
}

geography members

Member Type Required Description
geography: Use this match to test the requesting client’s location, either by continent, country, region, or designated market area (DMA). Each subcustomer policy can include up to ten geography matches.
name Enumeration Enter geography to match based on the requesting client’s geographic location.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
params geography.params Specifies any geographic area to match. You need to include at least one continent, country, region, or dma type, and at least one value for each type, if specified. Any specified value matches, so if you include NA (North America) as a continent, you don’t need to include US as a country.
value String All match criteria require the value member, but geography does not use one. Specify a dash for this member (-).
geography.params: Specifies any geographic area to match. You need to include at least one continent, country, region, or dma type, and at least one value for each type, if specified. Any specified value matches, so if you include NA (North America) as a continent, you don’t need to include US as a country.
continent Array Specify a list of two-letter continents to match: AF for Africa, AS for Asia, EU for Europe, NA for North America, OC for Oceania, SA for South America, and OT for all others.
country Array Specify a list of two-letter countries to match. For example, US for United States and IN for India. A list of supported Country Codes is available for download on Akamai Control Center.
dma Array This only applies to the United States. Specify a list of numeric designations as string values to serve as designated market area (DMA) codes. A DMA is a specific Nielsen Media Research area in which the population can receive the same, or similar Internet media offerings. A list of supported DMA Codes is available on Control Center.
ipFromHeader Enumeration When matching the X-Forwarded-For header for the source, specifies which geographic client IP information to match, either the first client IP listed for a specified geographic location, or all to match any. The default is first.
region Array Specify a list of regions to match. Use the two letter designation for a specific region (state or territory), prefaced with the applicable country and a colon. For example, US:CA for California, United States or CA:BC for British Columbia, Canada. A list of supported Country Codes and State or Region Codes is available on Control Center.
source Enumeration Specifies where to find the geographic information, either connectingIp to use the requesting client’s IP address, headers to use the X-Forwarded-For header, or both to match either location. The default is both.

Associated behaviors are applied if a header or header value you specify in this match criteria are included with a request.

Download schema: header-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "header",
            "value": "header-name header-value1 header-value2",
            "negated": false
        }
    ],
    "behaviors": []
}

header members

Member Type Required Description
header: Associated behaviors are applied if a header or header value you specify in this match criteria are included with a request.
name Enumeration Enter header to match on an incoming request header or header value.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter a header name, and optionally include an associated header value, for the match (for example, Some-Header-Name or Some-Header-Name "some string value" "another value" or ). Separate multiple header value entries with spaces. Header values are also case sensitive.

host-name

Include this to match on hostnames listed in the incoming request’s Host header.

Download schema: host-name-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "host-name",
            "value": "host-name1 host-name2 host-name3",
            "negated": false
        }
    ],
    "behaviors": []
}

host-name members

Member Type Required Description
host-name: Include this to match on hostnames listed in the incoming request’s Host header.
name Enumeration Enter host-name to match on hostnames listed in the incoming request’s Host header.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter a space-separated list of hostnames to match. You can use the ? and * wildcards with this match value.

http-method

Include this to match on a set of HTTP methods included in a client request.

Download schema: http-method-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "http-method",
            "value": "PUT POST",
            "negated": true
        }
    ],
    "behaviors": []
}

http-method members

Member Type Required Description
http-method: Include this to match on a set of HTTP methods included in a client request.
name Enumeration Enter http-method to match based on HTTP method.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter the HTTP methods to match on, separated by spaces. The following values are supported: GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, and CONNECT.

url-extension

Include this to match on the extension in the incoming request. This match criteria has no effect on URL paths that do not include a file extension.

Download schema: url-extension-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-extension",
            "value": "jpg png gif",
            "negated": false
        }
    ],
    "behaviors": []
}

url-extension members

Member Type Required Description
url-extension: Include this to match on the extension in the incoming request. This match criteria has no effect on URL paths that do not include a file extension.
name Enumeration Enter url-extension to match on the extension in the incoming request.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter the filename extensions to match on, separated by spaces. This string cannot be empty and entries are case sensitive.

url-filename

Include this to match on the filename and extension included in the incoming request.

Download schema: url-filename-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-filename",
            "value": "filename.ext myfile.ext",
            "negated": false
        }
    ],
    "behaviors": []
}

url-filename members

Member Type Required Description
url-filename: Include this to match on the filename and extension included in the incoming request.
name Enumeration Enter url-filename to match on the filename and extension included in the incoming request.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter a space-separated list of filenames to match. Wildcards are not supported. (Include the full name of the target file.) The filename can be in any subdirectory or URL path. For example, filename.ext matches on both /filename.ext and /path/to/filename.ext.

url-path

Include this to match on the first path component in the incoming request. The first path component is the section directly after the base URL.

Download schema: url-path-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-path",
            "value": "new-files old-files",
            "negated": false
        }
    ],
    "behaviors": []
}

url-path members

Member Type Required Description
url-path: Include this to match on the first path component in the incoming request. The first path component is the section directly after the base URL.
name Enumeration Enter url-path to match on the first path component in the incoming request.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter a space-separated list of path names to match on. Do not include slashes with your entry. This match is case sensitive and does not support wildcard characters. For example, entering new-files old-files matches on all URI paths that begin with /new-files/ or /old-files/, like /new-files/dir1/dir2/filename.ext.

url-querystring

Include this to match on a combination of query string parameters and their values.

Download schema: url-querystring-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-querystring",
            "params": [
                {
                    "key": "test*"
                },
                {
                    "key": "version*",
                    "values": "beta* *test*"
                },
                {
                    "key": "mode",
                    "values": "bypass"
                }
            ],
            "negated": false
        }
    ],
    "behaviors": []
}

url-querystring members

Member Type Required Description
url-querystring: Include this to match on a combination of query string parameters and their values.
name Enumeration Enter url-querystring to match on a combination of query string parameters and their values.
params url-querystring.params[] The parameters that define how you want to handle query strings for your implementation.
url-querystring.params[]: The parameters that define how you want to handle query strings for your implementation.
key String Enter the query string to match on. You can use the ? and * wildcards with your entry.
value String Enter the query string values to match on, separated by spaces. You can use the ? and * wildcards with this match value.

url-scheme

Include this to match on the protocol or scheme (HTTP or HTTPS) of an incoming request.

Download schema: url-scheme-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-scheme",
            "value": "HTTP",
            "negated": true
        }
    ],
    "behaviors": []
}

url-scheme members

Member Type Required Description
url-scheme: Include this to match on the protocol or scheme (HTTP or HTTPS) of an incoming request.
name Enumeration Enter url-scheme to match on the protocol or scheme (HTTP or HTTPS) of an incoming request.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value Enumeration Enter either HTTP or HTTPS depending on the protocol you want to match on.

url-wildcard

Include this match to use wildcards when matching on the incoming request path, minus any query strings. This match type only supports the * wildcard.

Download schema: url-wildcard-match.json

Sample inclusion for this match in a PUT policy operation:

{
    "matches": [
        {
            "name": "url-wildcard",
            "value": "/styles/* /images/baseball.png",
            "negated": false
        }
    ],
    "behaviors": []
}

url-wildcard members

Member Type Required Description
url-wildcard: Include this match to use wildcards when matching on the incoming request path, minus any query strings. This match type only supports the * wildcard.
name Enumeration Enter url-wildcard to use wildcards when matching on the incoming request path, minus query strings.
negated Boolean If set to true, Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria.
value String Enter the path to match on. If you do not include a wildcard, the incoming request must match the value exactly as entered.

access-control

Include this behavior to allow or deny client requests based on what’s specified as the matches criteria.

Download schema: access-control-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "access-control",
            "type": "denied",
            "value": "deny-protocol"
        }
    ]
}

access-control members

Member Type Required Description
access-control: Include this behavior to allow or deny client requests based on what’s specified as the matches criteria.
name Enumeration Enter access-control to deny client requests based on any of the available match conditions.
type Enumeration Either deny or allow an incoming request that matches on this rule.
value String Enter strings of up to 64 characters to annotate logs with the approval or denial reason. Alphanumeric characters, dashes, and underscores are valid. For a type of allow, you can also use the * wildcard character. Separate strings with spaces.

cachekey-query-args

Include this behavior to determine how query string arguments within an incoming request should be handled.

Download schema: cachekey-query-args-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "cachekey-query-args",
            "type": "include",
            "value": "product=1"
        }
    ]
}

cachekey-query-args members

Member Type Required Description
cachekey-query-args: Include this behavior to determine how query string arguments within an incoming request should be handled.
name Enumeration Enter cachekey-query-args to define how query-string arguments are handled when creating the cache key for the Akamai edge server.
type Enumeration Options for handling query-string arguments. Use include-all to include all query-string values in the cache key. Use include to only append the query arguments listed in the cache key’s value attribute. Use ignore-all to remove all query-string arguments from the incoming request. Use ignore to not include the query arguments listed in the value attribute in the cache key.
value String If using include or ignore as the caching type, list the query strings to match on. The match is case sensitive. Use spaces to separate entries. Add an equal sign to the value to match the query string argument exactly and also extend the value of the query argument. For example, entering product=1 matches both product=1 and product=123 but not product=234. Not required for the include-all and ignore-all type settings.

caching

Include this behavior to define time-to-live (TTL) cache settings for subcustomers.

Download schema: caching-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "caching",
            "type": "fixed",
            "value": "86400s"
        }
    ]
}

caching members

Member Type Required Description
caching: Include this behavior to define time-to-live (TTL) cache settings for subcustomers.
name Enumeration Enter caching to configure the time-to-live (TTL) settings for a subcustomer based on specific match conditions.
type Enumeration Select the type of cache response to use. Choose no-store to never cache the response and evict any existing cache entry; bypass-cache to never cache the response and retain the existing cache entry; fixed to cache the response for the time period defined in value; honor to cache based on the values in the cache-control and expires headers; honor-cc to cache based on the values in the cache-control header; or honor-expires to cache based on the values in the expires header.
For the honor-based options, objects currently in cache may be used with the current request. Also, if the response doesn’t include the Cache-Control or Expires header, the object is cached based on the time listed in the value parameter. For the honor and honor-cc options, if the Cache-Control header includes a no-store or no-cache directive, the Akamai server doesn’t cache the response.
No caching occurs if the Expires header has an RFC 2616 time string in the past or includes -1, which helps prevent downstream caching.
value String Ignored for the no-store and bypass-cache types. For all other type settings, enter a simple duration string, which is an integer followed by a specifier to represent seconds (s), minutes (m), hours (h), or days (d). For example: 86400s, or 1440m, or 24h, or 1d all represent a TTL setting of one day.

content-characteristics-dynamic-web-content

Include the content-characteristics behavior and set the type to dynamic-web-content if you’re using Integrated Cloud Acceleration, to use SureRoute to optimize the forward path to the origin server. It controls embedded object pre-fetching, situational image compression, and Real User Monitoring (RUM) capabilities.

Download schema: content-char-dynamic-web-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-characteristics",
            "type": "dynamic-web-content",
            "value": "-",
            "params": {
                "mobileImageCompressionEnabled": true,
                "prefetchEnabled": false,
                "realUserMonitoringEnabled": true,
                "sureRouteTestObjectPath": "/sureroute"
            }
        }
    ]
}

content-characteristics-dynamic-web-content members

Member Type Required Description
content-characteristics-dynamic-web-content: Include the content-characteristics behavior and set the type to dynamic-web-content if you’re using Integrated Cloud Acceleration, to use SureRoute to optimize the forward path to the origin server. It controls embedded object pre-fetching, situational image compression, and Real User Monitoring (RUM) capabilities.
name Enumeration Enter content-characteristics, the behavior that includes this optimization.
params content-characteristics-dynamic-web-content.params Optimization settings for this behavior.
type Enumeration Enter dynamic-web-content to use Akamai’s SureRoute feature to optimize the forward path to the origin server.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-characteristics-dynamic-web-content.params: Optimization settings for this behavior.
mobileImageCompressionEnabled Boolean Enable or disable JPEG compression based on mobile network conditions.
prefetchEnabled Boolean Inspects HTML responses and prefetches embedded objects in HTML files. Prefetching works on any page that includes <img>, <script>, or <link> tags that specify relative paths. It also works when the resource hostname matches the request domain in the HTML file, and it is part of a fully qualified URI. When set to true, edge servers prefetch objects with the following file extensions: aif, aiff, au, avi, bin, bmp, cab, carb, cct, cdf, class, css, doc, dcr, dtd, exe, flv, gcf, gff, gif, grv, hdml, hqx, ico, ini, jpeg, jpg, js, mov, mp3, nc, pct, pdf, png, ppc, pws, swa, swf, txt, vbs, w32, wav, wbmp, wml, wmlc, wmls, wmlsc, xsd, and zip.
sureRouteTestObjectPath String Enable SureRoute by entering a valid path to the test object on your origin. A valid test object is between 4 KB to 12 KB compressed and requires no authorization. SureRoute looks for the optimal route between an edge server and an origin server.

content-characteristics-large-files

Include the content-characteristics behavior and set the type to large-files to optimize the delivery of large file downloads of up to 1.8 GB. This behavior uses partial object caching with pre-fetched object data.
As a best practice, only use this behavior if you serve large files. Otherwise, the Akamai platform may send additional requests to your origin. When using Large File Optimization, if an object doesn’t meet the minimum size criterion of 10 MB, the platform requests the entire object from the origin.

Download schema: content-char-large-file-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-characteristics",
            "type": "large-files",
            "value": "-",
            "params": {
                "objectSize": "10mbto100mb"
            }
        }
    ]
}

content-characteristics-large-files members

Member Type Required Description
content-characteristics-large-files: Include the content-characteristics behavior and set the type to large-files to optimize the delivery of large file downloads of up to 1.8 GB. This behavior uses partial object caching with pre-fetched object data.
As a best practice, only use this behavior if you serve large files. Otherwise, the Akamai platform may send additional requests to your origin. When using Large File Optimization, if an object doesn’t meet the minimum size criterion of 10 MB, the platform requests the entire object from the origin.
name Enumeration Enter content-characteristics, the behavior that includes this optimization.
params content-characteristics-large-files.params The parameters that define how you want to handle file optimization for your implementation.
type Enumeration Enter large-files to optimize the delivery of large file downloads of up to 1.8 GB.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-characteristics-large-files.params: The parameters that define how you want to handle file optimization for your implementation.
objectSize Enumeration Options include: lt1mb for objects less than 1 MB, 1mbto10mb for objects 1 MB to 10 MB, 10mbto100mb for objects 10 MB to 100 MB, and gt100mb for objects 100 MB and larger. Both 10mbto100mb and gt100mb enable Large File Optimization. Using lt1mb or 1mbto10mb disables partial object caching and prevents the platform from serving large objects.

content-characteristics-on-demand-streaming

Include the content-characteristics behavior and set the type to streaming-video-on-demand to optimize caching and network timeout conditions for on-demand video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings.

Download schema: content-char-vod-streaming-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-characteristics",
            "type": "streaming-video-on-demand",
            "value": "-",
            "params": {
                "segmentDurationDASH": "3.0",
                "segmentDurationHDS": "4.0",
                "segmentDurationHLS": "7.0",
                "segmentDurationSmooth": "3.0",
                "prefetch": {
                    "originAssist": true
                }
            }
        }
    ]
}

content-characteristics-on-demand-streaming members

Member Type Required Description
content-characteristics-on-demand-streaming: Include the content-characteristics behavior and set the type to streaming-video-on-demand to optimize caching and network timeout conditions for on-demand video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings.
name Enumeration Specify content-characteristics, the behavior that includes this optimization.
params content-characteristics-on-demand-streaming.params The parameters that define how you want to handle on-demand video streaming.
type Enumeration Specify streaming-video-on-demand to optimize cache and network timeout conditions for on-demand video content.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-characteristics-on-demand-streaming.params: The parameters that define how you want to handle on-demand video streaming.
prefetch content-characteristics-on-demand-streaming.params.prefetch To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media.
segmentDurationDASH Number The duration in seconds for Dynamic Adaptive Streaming over HTTP (DASH) media segments for this subcustomer. The supported range is 0 to 15, with only one decimal place allowed. If you omit this member, ACE uses the duration set for DASH Segment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default segment duration for DASH (6.0 seconds).
segmentDurationHDS Number The duration in seconds for HTTP Dynamic Streaming (HDS) media fragments for this subcustomer. The supported range is 0 to 15, with only one decimal place allowed. If you omit this member, ACE uses the duration set for HDS Fragment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default fragment duration for HDS (6.0 seconds).
segmentDurationHLS Number The duration in seconds for HTTP Live Streaming (HLS) media segments. The supported range is 0 to 15, with only one decimal place allowed. For recommended best practices, see Apple Technical Note 2224. If you omit this member, ACE uses the duration set for HLS Segment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default segment duration for HLS (10.0 seconds).
segmentDurationSmooth Number The duration in seconds for Microsoft Smooth Streaming media fragments. The supported range is 0 to 15, with only one decimal place allowed. If you omit this member, ACE uses the duration set for Smooth Fragment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default fragment duration for Smooth (2.0 seconds).
content-characteristics-on-demand-streaming.params.prefetch: To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media.
originAssist Boolean This enables prefetching using the origin-assist scheme. When Akamai fetches an object from an origin, the response needs to include a new header that lists the next object in the sequence. Akamai can read this information and prefetch this object. This scheme relies on assistance from your “intelligent” origin to trigger prefetching. Requirements and setup of an origin are explained in the Akamai Cloud Embed - Implementation Guide.

content-characteristics-live-streaming

Include the content-characteristics behavior and set the type to streaming-video-live to optimize caching and network timeout conditions for live video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings.

Download schema: content-char-live-streaming-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-characteristics",
            "type": "streaming-video-live",
            "value": "-",
            "params": {
                "segmentDurationDASH": "3.0",
                "segmentDurationHDS": "4.0",
                "segmentDurationHLS": "7.0",
                "segmentDurationSmooth": "3.0",
                "prefetch": {
                    "originAssist": true
                }
            }
        }
    ]
}

content-characteristics-live-streaming members

Member Type Required Description
content-characteristics-live-streaming: Include the content-characteristics behavior and set the type to streaming-video-live to optimize caching and network timeout conditions for live video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings.
name Enumeration Specify content-characteristics, the behavior that includes this optimization.
params content-characteristics-live-streaming.params The parameters that define how you want to handle live video streaming.
type Enumeration Specify streaming-video-live to optimize delivery for live video content.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-characteristics-live-streaming.params: The parameters that define how you want to handle live video streaming.
prefetch content-characteristics-live-streaming.params.prefetch To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media.
segmentDurationDASH Number The duration in seconds for Dynamic Adaptive Streaming over HTTP (DASH) media segments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default segment duration for DASH (6.0 seconds).
segmentDurationHDS Number The duration in seconds for HTTP Dynamic Streaming (HDS) media fragments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default fragment duration for HDS (6.0 seconds).
segmentDurationHLS Number The duration in seconds for HTTP Live Streaming (HLS) media segments. The supported range is 0 to 10, with only one decimal place allowed. For recommended best practices, see Apple Technical Note 2224. If you omit this member, ACE uses the default segment duration for HLS (10.0 seconds).
segmentDurationSmooth Number Duration in seconds for Microsoft Smooth Streaming media fragments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default fragment duration for Smooth (2.0 seconds).
content-characteristics-live-streaming.params.prefetch: To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media.
originAssist Boolean This enables prefetching using the origin-assist scheme. When Akamai fetches an object from an origin, the response needs to include a new header that lists the next object in the sequence. Akamai can read this information and prefetch this object. This scheme relies on assistance from your “intelligent” origin to trigger prefetching. Requirements and setup of an origin are explained in the Akamai Cloud Embed - Implementation Guide.

content-compression

Include this behavior to provide compression settings. You can enable gzip compression, decompress objects before delivering them to the client, or maintain the origin’s compression settings.

Download schema: content-compression-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-refresh",
            "type": "date-time",
            "value": "2018-12-31T11:59:59Z",
            "params": {
                "mustRevalidate": true
            }
        }
    ]
}

content-compression members

Member Type Required Description
content-compression: Include this behavior to provide compression settings. You can enable gzip compression, decompress objects before delivering them to the client, or maintain the origin’s compression settings.
name Enumeration Enter content-compression to enable this behavior.
type Enumeration Select the appropriate compression setting for this behavior. Use always to compress all objects served to clients that send an Accept-Encoding:*gzip* header, never to decompress objects served to the client, and follow-origin to retain the origin’s compression settings.
value String Enter the MIME types to compress, separated by spaces. The maximum string length is 1024 characters, and wildcards can be used (*). Enter - if you do not want to apply compression to any MIME type.

content-refresh

Include this behavior to invalidate the CDN cache at an explicit date and time. This behavior uses epoch time to denote when a request should receive a new copy of the object or a newly validated one.

Download schema: content-refresh-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "content-refresh",
            "type": "epoch",
            "value": "1543273814",
            "params": {
                "mustRevalidate": true
            }
        }
    ]
}

content-refresh members

Member Type Required Description
content-refresh: Include this behavior to invalidate the CDN cache at an explicit date and time. This behavior uses epoch time to denote when a request should receive a new copy of the object or a newly validated one.
name Enumeration Enter content-refresh to invalidate CDN cache at an explicit date/time.
params content-refresh.params Settings used by this behavior to reapply validation to content.
type Enumeration Declares the format of the value element. Enter epoch to use epoch time; date-time to use an ISO 8601 time value (YYYY-MM-DDThh:mm:ssZ); date to use an ISO 8601 date value (YYYY-MM-DD), which invalidates cache at midnight GMT on the specified date; and natural to invalidate content immediately upon publication of the content policy.
value String The time after which the invalidation of objects in cache should occur.
content-refresh.params: Settings used by this behavior to reapply validation to content.
mustRevalidate Boolean If true, the edge server only serves content from cache if it has been validated again after the given invalidation time. If false, the edge server may serve content from cache if an attempt to validate the content again fails to receive a response from the origin server.

downstream-caching

Include this behavior to control downstream caching of alternate content. Only use this behavior if site failover is enabled for the alternate hostname property. If you do not include this behavior, your subcustomer policy uses the downstream caching settings specified in the alternate hostname property. To enable site failover, use the Subcustomer Enablement behavior in Property Manager.

Download schema: downstream-caching-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "downstream-caching",
            "value": "no-store"
        }
    ]
}

downstream-caching members

Member Type Required Description
downstream-caching: Include this behavior to control downstream caching of alternate content. Only use this behavior if site failover is enabled for the alternate hostname property. If you do not include this behavior, your subcustomer policy uses the downstream caching settings specified in the alternate hostname property. To enable site failover, use the Subcustomer Enablement behavior in Property Manager.
name Enumeration Enter downstream-caching to control downstream caching of alternate content.
value Enumeration Enter no-store to serve the alternate response with an HTTP Cache-Control: no-store header. Enter no-cache to serve the alternate response with an HTTP Cache-Control: no-cache header.

geo-blacklist

Include this behavior to block (“blacklist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are allowed.

Download schema: geo-blacklist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "geo-blacklist",
            "type": "region",
            "value": "US:CA US:OR US:WA US:ID US:AZ US:NV"
        }
    ]
}

geo-blacklist members

Member Type Required Description
geo-blacklist: Include this behavior to block (“blacklist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are allowed.
name Enumeration Enter geo-blacklist to block access to content based on the geographic location of the requesting IP address.
type Enumeration Declares the type of geographies to blacklist. Valid types are continent, country, region, and dma.
value String Enter a space-separated list of geographic areas to blacklist. Proper values for these areas are maintained in the EdgeScape Data Codes lists on Akamai Control Center. Each continent and country follows a two-digit format. If matching on region values, these follow a country:region format like US:AK (Alaska in the United States). If matching on dma, enter the integer that represents the Designated Market Area (DMA). Larger areas are include smaller ones, so if you include NA (North America) as a continent, you don’t need to include US as a country.

geo-whitelist

Include this behavior to allow (“whitelist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are denied.

Download schema: geo-whitelist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "geo-whitelist",
            "type": "country",
            "value": "US:CA US:OR US:WA US:ID US:AZ US:NV"
        }
    ]
}

geo-whitelist members

Member Type Required Description
geo-whitelist: Include this behavior to allow (“whitelist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are denied.
name Enumeration Enter geo-whitelist to allow access to content based on the geographic location of the requesting IP address.
type Enumeration Declares the type of geographies to whitelist. Valid types include: continent, country, region, and dma.
value String Enter a space-separated list of geographic areas to whitelist. Proper values for these areas are maintained in the EdgeScape Data Codes lists on Control Center. Each continent and country follows a two-digit format. If matching on region values, these follow a country:region format like US:AK (Alaska in the United States). If matching on dma, enter the integer that represents the Designated Market Area (DMA). Larger areas are inclusive of smaller ones, so if you include NA (North America) as a continent, you don’t need to include US as a country.

ip-blacklist

Include this behavior to block (“blacklist”) access based on the requesting IP address. All other requesting IP addresses are allowed access.

Download schema: ip-blacklist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "ip-blacklist",
            "value": "10.10.1.100 10.10.2.100 10.10.3.100"
        }
    ]
}

ip-blacklist members

Member Type Required Description
ip-blacklist: Include this behavior to block (“blacklist”) access based on the requesting IP address. All other requesting IP addresses are allowed access.
name Enumeration Enter ip-blacklist to block access based on the requesting IP address.
value String Enter a space-separated list of IP addresses or CIDR blocks to deny. All other IP addresses are allowed.

ip-whitelist

Include this behavior to allow (“whitelist”) access based on the requesting IP address. Only the IP addresses listed are allowed access.

Download schema: ip-whitelist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "ip-whitelist",
            "value": "10.10.1.100 10.10.2.100 10.10.3.100"
        }
    ]
}

ip-whitelist members

Member Type Required Description
ip-whitelist: Include this behavior to allow (“whitelist”) access based on the requesting IP address. Only the IP addresses listed are allowed access.
name Enumeration Enter ip-whitelist to allow access based on the requesting IP address.
value String Enter a space-separated list of IP addresses or CIDR blocks to allow. All other IP addresses are blocked.

modify-outgoing-request-header

Include this behavior to modify the outgoing request headers sent from Akamai to an origin. This also works on request headers sent from a client if the request is sent back to the origin, but not a cache hit.

Download schema: modify-outgoing-request-header-behavior.json

Sample of this behavior in a policy to append the header values, add_this_value and also_add_this_value to the outgoing request header, header1; append add_this_value to the outgoing request header, header2; and set a comma plus a space (,) as the delimiter:

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-request-header",
            "type": "append",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": "add_this_value, also_add_this_value"
                    },
                    {
                        "header2": "add_this_value"
                    }
                ],
                "delimiter": ", "
            }
        }
    ]
}

Sample of this behavior in a policy to delete the header values, this_is_an_old_value and this_is_an_older_value from the outgoing request header, header1; delete the empty header, header2; and set the semicolon and a space (;) set as a delimiter:

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-request-header",
            "type": "delete",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": "this_is_an_old_value; this_is_an_older_value"
                    },
                    {
                        "header2": ""
                    }
                ],
                "delimiter": "; "
            }
        }
    ]
}

Sample of this behavior in a policy to match the header, header1 and overwrite its header value with replace_with_this_new_header_value (with no delimiter, because an overwrite doesn’t use one):

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-request-header",
            "type": "overwrite",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": "replace_with_this_new_header_value"
                    }
                ]
            }
        }
    ]
}

modify-outgoing-request-header members

Member Type Required Description
modify-outgoing-request-header: Include this behavior to modify the outgoing request headers sent from Akamai to an origin. This also works on request headers sent from a client if the request is sent back to the origin, but not a cache hit.
name Enumeration Set to modify-outgoing-request-header to modify an outgoing request header.
params modify-outgoing-request-header.params Use these members to provide attributes to modify outgoing request headers.
type Enumeration Specifies the type of modification to perform if the request meets the criteria set in the rule’s match. Set this to append to add a given header value to a header name set in the headerList. Set this to delete to remove a given header value from a header name set in the headerList. Set this to overwrite to match on a specified header name and replace its existing header value with a new one you specify. Caveats apply to each type.
value String This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (-).
modify-outgoing-request-header.params: Use these members to provide attributes to modify outgoing request headers.
delimiter Enumeration Specifies the delimiter to be used when indicating multiple values for a header. Set this to a <space>, , (comma), ; (semicolon), ,<space> (comma and space), or ;<space> (semicolon and space). Delimiters are only supported for use with append and delete. Caveats apply to delimiter use. This defaults to a , if nothing is set.
headerList Array A collection of key value pairs that specify the headers and associated values to be modified. The key sets the header name to be modified and the value is the header value to be appended, deleted or overwritten. Various caveats apply to header names and values.

Usage caveats

Consider the following usage caveats before applying this behavior.

  • You can modify a maximum of 15 request headers with this behavior, in a single policy.

  • You can use each behavior type (append, delete, and overwrite) once in a single rule.

  • You can’t modify the same header more than once in a single policy.

  • You can use multiple modify-outgoing-request-header behaviors in the same rule. Ensure they don’t conflict, based on other caveats in this list. (This only applies to this behavior.)

  • You can’t use a CRLF or a colon in header names or header values.

  • The append and overwrite behavior types create a non-existent header and apply the specified header value.

  • The append behavior type won’t append a header value if it already exists in the header. If duplicate instances of a header value are identified, they are left as is because the append type only adds content, it does not remove anything. Use the overwrite type in this scenario to completely replace the header content, and remove duplicate values.

  • If multiple occurrences of a single header are included in a request, an append or delete behavior type only applies to the first occurrence. That header is modified and sent to the origin, and all other instances of the same header in the request are ignored. If you don’t include the modify-outgoing-request-header, all occurrences of a request header are sent to the origin.

  • The delete behavior type can be used to remove an empty header. (If it has no header value.) Just include the header name, and leave the header value empty (for example, "my_header": "").

  • The delete behavior type only removes a value from a header if that value is found. If the value isn’t found, it does nothing.

  • If the delete behavior type removes the only header value, older origin servers may experience issues. (This can result in a “null pointer exception” on an older origin server not built to handle empty headers.)

  • When delimiter-separating multiple header values in a delete, values are deleted only if they exist in the order specified. For example, if the policy is set to match and delete "header1": "value1,value3", and the actual request header is "header1: value1,value2,value3", nothing is deleted, because the exact match, "value1,value3" wasn’t found. However, if the actual request header is "header1: value2,value1,value3", value1 and value3 are deleted because they match the order set.

  • The overwrite behavior type overwrites all header value information for a header name it matches.

  • If you don’t include the delimiter object, it defaults to a comma.

  • If you use a delimiter to include a list of header values, it must match what’s set for the delimiter member (or a comma if you didn’t set one.) Otherwise, the API matches on exactly what’s set.

  • If you include a delimiter when using the overwrite behavior type, Akamai Cloud Embed ignores it.

  • Header names are case-insensitive when matching eligible headers, for all behavior types.

  • Header values are case-sensitive when matching eligible headers for append and delete. (Header values are replaced for overwrite, so no matching is performed.)

  • Since header names are case-insensitive, the header name you set in a policy is what’s used as the header name once modified.

Blacklisted Request Headers

These headers can’t be modified. If the type criteria set matches one of these headers, an error is revealed. Both header names and values are case-insensitive when matching on blacklisted headers. The * represents a wildcard.

  • Connection
  • Content-Length
  • Forwarded
  • Host
  • TE
  • Upgrade
  • x-akamai*
  • x-cache*
Blacklisted header values

You can’t modify these items in a header value.

  • akamai-x-*
Known Issue: Appending multiple header values and duplicate, existing values

When you use the append behavior type and include multiple header values, if a header value already exists, this behavior duplicates it in the resulting header.

For example, assume you have the existing header, "header1": "value1;value2" and you set this behavior to append: "header1": "value1;value3;value4". This results in "header1: value1;value2;value1;value3;value4". This is because the API is trying to match on the full value you’ve specified, "value1;value3;value4" when checking for duplicates.

As a best practice, you should only include multiple header values for an append if you’re sure one of those values doesn’t already exist.

modify-outgoing-request-path

Include this behavior to provide options for altering the request URL before it is sent to origin.

Download schema: modify-outgoing-request-path-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-request-path",
            "type": "replace",
            "value": "/dir1/dir2/###/dir4/"
        }
    ]
}

modify-outgoing-request-path members

Member Type Required Description
modify-outgoing-request-path: Include this behavior to provide options for altering the request URL before it is sent to origin.
name Enumeration Enter modify-outgoing-request-path to alter the request URL before it is sent to origin.
type Enumeration Set the type of request path change to use. Enter remove to remove the first occurrence of the value from the outgoing request URL; replace-all to replace the original request path before the filename with the path specified in value; or replace to search for a portion of the original request URL and replace it with a value you define.
value String If using remove, enter the string of characters to remove from the forward request. The behavior doesn’t remove leading and trailing slashes. If using replace-all, enter the URL path to replace the original incoming URL path. If using replace, enter a value in this format: /find/path/###/replace/ path/, where ### separates the string to find and the string to replace. For example, if your base URL is www.example.com/dir1/dir2/dir3/index.html and you enter /dir1/dir2/###/dir4/ as the value, the resulting URL is www.example.com/dir4/dir3/index.html.

modify-outgoing-response-header

Include this behavior to modify the outgoing response headers sent from the Edge server back to the client.

Download schema: modify-outgoing-response-header-behavior.json

Sample of this behavior in a policy to append the header value, new_value1 to the outgoing response header, header1; append the values newer_value1 and newest_value1 to the outgoing response header, header2; and set the semicolon (;) as the delimiter:

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-response-header",
            "type": "append",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": "new_value1"
                    },
                    {
                        "header2": "newer_value1;newest_value1"
                    }
                ],
                "delimiter": ";"
            }
        }
    ]
}

Sample of this behavior in a policy to delete the empty header, header1; and delete the header values, old_value, older_value, and oldest_value from the outgoing response header, header2 (The behavior only deletes these values if they exist in header2 in the order specified. See Usage caveats):

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-response-header",
            "type": "delete",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": ""
                    },
                    {
                        "header2": "old_value,older_value,oldest_value"
                    }
                ],
                "delimiter": ","
            }
        }
    ]
}

Sample of this behavior in a policy to match the header, header1 and overwrite its header value with use_this_instead (with no delimiter, because an overwrite doesn’t use one):

{
    "matches": [],
    "behaviors": [
        {
            "name": "modify-outgoing-response-header",
            "type": "overwrite",
            "value": "-",
            "params": {
                "headerList": [
                    {
                        "header1": "use_this_instead"
                    }
                ]
            }
        }
    ]
}

modify-outgoing-response-header members

Member Type Required Description
modify-outgoing-response-header: Include this behavior to modify the outgoing response headers sent from the Edge server back to the client.
name Enumeration Set to modify-outgoing-response-header to modify an outgoing response header.
params modify-outgoing-response-header.params Use these members to provide attributes to modify outgoing response headers.
type Enumeration Specifies the type of modification to perform if the response meets the criteria set in the rule’s match. Set this to append to add a given header value to a header name set in the headerList. Set this to delete to remove a given header value from a header name set in the headerList. Set this to overwrite to match on a specified header name and replace its existing header value with a new one you specify. Caveats apply to each type.
value String This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (-).
modify-outgoing-response-header.params: Use these members to provide attributes to modify outgoing response headers.
delimiter Enumeration Specifies the delimiter to be used when indicating multiple values for a header. Set this to a <space>, , (comma), ; (semicolon), ,<space> (comma and space), or ;<space> (semicolon and space). Delimiters are only supported for use with append and delete. Caveats apply to delimiter use. This defaults to a , if nothing is set.
headerList Array A collection of key value pairs that specify the headers and associated values to be modified. The key sets the header name to be modified and the value is the header value to be appended, deleted or overwritten. Various caveats apply to header names and values.

Usage caveats

Consider the following usage caveats before applying this behavior.

  • You can modify a maximum of 15 response headers with this behavior, in a single policy.

  • You can use each behavior type (append, delete, and overwrite) once in a single rule.

  • You can’t modify the same header more than once in a single policy.

  • You can’t use a CRLF or a colon in header names or header values.

  • The append and overwrite behavior types create a non-existent header and apply the specified header value.

  • The append behavior type won’t append a header value if it already exists in the header. If duplicate instances of a header value are identified, they are left as is because the append type only adds content, it does not remove anything. Use the overwrite type in this scenario to completely replace the header content, and remove duplicate values.

  • If multiple occurrences of a single header are included in a request, an append or delete behavior type only applies to the first occurrence. That header is modified and sent to the origin, and all other instances of the same header in the request are ignored. If you don’t include the modify-outgoing-response-header, all occurrences of a request header are sent to the origin.

  • The delete behavior type can be used to remove an empty header. (If it has no header value.) Just include the header name, and leave the header value empty (for example, "my_header": "")

  • The delete behavior type only removes a value from a header if that value is found. If the value isn’t found, it does nothing.

  • If the delete behavior type removes the only header value, older origin servers may experience issues. (This can result in a “null pointer exception” on an older origin server not built to handle empty headers.)

  • When delimiter-separating multiple header values in a delete, values are deleted only if they exist in the order specified. For example, if the policy is set to match and delete "header1": "value1,value3", and the actual request header is "header1: value1,value2,value3", nothing is deleted, because the exact match, "value1,value3" wasn’t found. However, if the actual request header is "header1: value2,value1,value3", value1 and value3 are deleted because they match the order set.

  • The overwrite behavior overwrites all header value information for a header name it matches.

  • If you don’t include the delimiter object, it defaults to a comma.

  • If you use a delimiter to include a list of header values, it must match what’s set for the delimiter member (or you must use commas if you didn’t set one.) Otherwise, the API matches on exactly what’s set.

  • If you include a delimiter when using the overwrite behavior type, Akamai Cloud Embed ignores it.

  • Header names are case-insensitive when matching eligible headers, for all behavior types.

  • Header values are case-sensitive when matching eligible headers for append and delete. (Header values are replaced for overwrite, so no matching is performed.)

  • Since header names are case-insensitive, the header name you set in a policy is what’s used as the header name once modified.

Blacklisted Response Headers

These headers can’t be modified. If the type criteria set matches one of these headers, an error is revealed. Both header names and values are case-insensitive when matching on blacklisted headers. The * represents a wildcard.

  • Age
  • Alt-Svc
  • Connection
  • Content-Encoding
  • Content-Length
  • Content-Range
  • Transfer-Encoding
  • Vary
  • x-akamai*
  • x-cache*
Blacklisted header values

You can’t modify the following items when they occur in a header value.

  • akamai-x-*
Known Issue: Appending multiple header values and duplicate, existing values

When you use the append behavior type and include multiple header values, if a header value already exists, this behavior duplicates it in the resulting header.

For example, assume you have the existing header, "header1": "value1;value2" and you set this behavior to append: "header1": "value1;value3;value4". This results in "header1: value1;value2;value1;value3;value4". This is because the API is trying to match on the full value you’ve specified, "value1;value3;value4" when checking for duplicates.

As a best practice, you should only include multiple header values for an append if you’re sure one of those values doesn’t already exist.

origin

Include this behavior to provide origin settings for the specific subcustomer. You need to include: origin DNS hostname, forward host header, and cache key. Optional settings include the origin base path and ports.

Download schema: origin-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "origin",
            "value": "-",
            "params": {
                "digitalProperty": "www.mysite.com",
                "originDomain": "c1234567.cloudprovider.com",
                "cacheKeyType": "origin",
                "cacheKeyValue": "-",
                "hostHeaderType": "digital_property",
                "hostHeaderValue": "-"
            }
        }
    ]
}

origin members

Member Type Required Description
origin: Include this behavior to provide origin settings for the specific subcustomer. You need to include: origin DNS hostname, forward host header, and cache key. Optional settings include the origin base path and ports.
name Enumeration Enter origin to set up the origin behavior. Akamai Cloud Embed requires an origin in every content policy.
params origin.params Origin settings for the policy.
value String Enter a dash (-) for this parameter.
origin.params: Origin settings for the policy.
cacheKeyType Enumeration Enter the method to use when constructing the cache key. Use digital_property if the response is different for each property, origin if the origin response is the same regardless of property, or fixed to set a specific cache key value.
cacheKeyValue String If cacheKeyType is fixed, enter a valid domain name for the hostname portion of the cache key. Use a dash (-) to indicate no value.
digitalProperty String Enter the hostname used by the client to access the site or application. Use a valid domain name like www.example.com or blogs.example.com.
hostHeaderType Enumeration For requests sent to this origin, enter the host header value to generate. Use digital_property to have the host header match the digital property, origin to use the originDomain value as the host header, and fixed to use the hostHeaderValue as the host header.
hostHeaderValue String If hostHeaderType is fixed enter a valid domain name to use in the host header. Use a dash (-) to indicate no value.
originDomain String Enter the origin hostname you provide to subcustomers when you provision services. Your entry can either be a valid domain name or an IP address.

origin-characteristics

Include this behavior if you have Integrated Cloud Acceleration (ICA), to select the type of origin supporting your Akamai Cloud Embed implementation. Use the origin behavior to configure origin settings for your subcustomers at the policy level.

Download schema: origin-characteristics-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "origin-characteristics",
            "value": "azure"
        }
    ]
}

origin-characteristics members

Member Type Required Description
origin-characteristics: Include this behavior if you have Integrated Cloud Acceleration (ICA), to select the type of origin supporting your Akamai Cloud Embed implementation. Use the origin behavior to configure origin settings for your subcustomers at the policy level.
name Enumeration Use the origin-characteristics behavior to select the type of origin you are using for your Akamai Cloud Embed implementation.
type Enumeration The type of origin supporting your implementation. Enter azure if you use an Azure Media Services live origin. Use unknown for all other origins.

origin-failover

This feature identifies primary origin connection failures based on a type you specify and marks that origin as “bad” after connections to all its IPs fail repeatedly. Rather than issuing a redirect to the end user, requests are failed over to a backup origin you call out. This improves response times, because the end user doesn’t have to wait several seconds for a connect-timeout on the forward request. Additionally, you specify a duration of time the primary origin is marked as bad. During this time, all requests are failed over to your backup origin. This relieves pressure on the primary by reducing the number of connection attempts, at a time when it appears to be having difficulties.

Download schema: origin-failover-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "origin-failover",
            "type": "backupOrigin",
            "value": "-",
            "params": {
                "errorType": "timeout",
                "originConnectionTimeout": "20s",
                "errorCountBeforeFailover": 10,
                "timeoutErrorCacheDuration": "2h",
                "backupOrigin": "backup.myorigin.com",
                "customForwardHost": "somebackuporigin.com"
            }
        }
    ]
}

origin-failover members

Member Type Required Description
origin-failover: This feature identifies primary origin connection failures based on a type you specify and marks that origin as “bad” after connections to all its IPs fail repeatedly. Rather than issuing a redirect to the end user, requests are failed over to a backup origin you call out. This improves response times, because the end user doesn’t have to wait several seconds for a connect-timeout on the forward request. Additionally, you specify a duration of time the primary origin is marked as bad. During this time, all requests are failed over to your backup origin. This relieves pressure on the primary by reducing the number of connection attempts, at a time when it appears to be having difficulties.
name Enumeration Set to origin-failover to add this to your policy to configure offload of failover detection and recovery.
params origin-failover.params These parameters are used to define your backup origin as well as what’s used to mark an origin as bad, in order to failover requests to that backup origin.
type String Specifies the type of failover to use if the request meets the criteria set in the rule’s match. Set this to backupOrigin to failover to a backup origin.
value String This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (-).
origin-failover.params: These parameters are used to define your backup origin as well as what’s used to mark an origin as bad, in order to failover requests to that backup origin.
backupOrigin String The domain name (the complete path and hostname) or IP address of the origin serving as your backup for failover.
customForwardHost String Include this to customize what’s included in the X-Forwarded-Host header, when a failover directs the request to a backupOrigin. (This header typically identifies the original host requested by the client in the Host HTTP request header.)
errorCountBeforeFailover Integer This tells Akamai how many errors of the selected errorType, timeout to recognize before an origin is considered bad, and failover is applied. As a best practice, set this to a value higher than 1. An origin shouldn’t be considered bad after only a single failure. Note that the default for this is 0. So, if you don’t set a value, all error requests are failed over and the first failed request marks the origin as bad. There are additional caveats that apply to this member, specifically when a request is actually failed over.
errorType Enumeration This defines the type of error that occurs to mark the connection as a failure. Set this to timeout to indicate a failure once an origin connection request times out after a specific amount of time. Caveats apply to the use of timeout. (Currently, only timeout is supported. You can expect additional errorType values with a future release.)
originConnectionTimeout String The amount of time that constitutes an origin connection timeout and results in a failure. If you leave this parameter out, the connection timeout is default set to five seconds.
timeoutErrorCacheDuration String Set an amount of time that needs to pass before a request retries an origin IP that was flagged as bad, as a result of a timeout error.

Usage caveats

Consider the following usage caveats before applying this behavior.

  • Failover to your specified backupOrigin happens under two conditions: when a timeout request error occurs; or when an origin receives a request after ACE has marked it as bad,because the errorCountBeforeFailover count has been reached. (Each timeout request error counts toward this total.) Marking an origin as bad stops connection attempts to it while it may be having trouble.

  • This behavior has two primary functions: To failover error requests to a backupOrigin you specify, and to mark an origin as “bad” after a certain number of these error requests occur, to stop further requests to a potentially origin when it may be having trouble.

  • The Akamai server tries a failed connection one more time before counting it towards your errorCountBeforeFailover.

  • The errorCountBeforeFailover member marks an origin as bad for the request that occurs after the quantity you’ve specified, and enacts the timeoutErrorCacheDuration to stop requests from targeting the origin for that length of time. Each subsequent request is then failed over to the backupOrigin. For example, if you set this to six, the seventh failed request triggers the timeoutErrorCacheDuration and the eighth and subsequent requests are failed over to your backupOrigin.

  • When used with the Origin behavior in a policy, set its cacheKeyType member to origin. This keeps cache key creation for your primary origin consistent with the Origin Failover behavior cache key creation for your backup origin.

  • During failover to your backup origin, the cache key is modified by adding a “b-” in the path. This avoids cache sharing and negative Time to Live (TTL) settings that may use what is in cache instead of accessing your specified backup origin. For example, assume a request is sent to this origin that has been as marked as bad: /prodtest-ff.qa.akamai.com.partnerdomain.net/OD/bird.jpg The request is rerouted to this backup origin and b- is added to the origin hostname: /b-mde-origin.qa.akamai.com.partnerdomain.net/OD/bird.jpg

  • Duration values allow for settings in days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). All default values are applied in seconds.

  • If you’ve enabled Tiered Distribution in your base configuration, origin failover is only valid for the top-tier level. (This represents the “last hop” to your origin to request content.)

referer-blacklist

Include this behavior to block (“blacklist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served by Akamai Cloud Embed from a domain trusted by the content owner.

Download schema: referer-blacklist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "referer-blacklist",
            "value": "/dir1/dir2/###/dir4/"
        }
    ]
}

referer-blacklist members

Member Type Required Description
referer-blacklist: Include this behavior to block (“blacklist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served by Akamai Cloud Embed from a domain trusted by the content owner.
name Enumeration Enter referer-blacklist to block access based on the Referer request header.
value String Enter a space-separated list of Referer header values to disallow. Use the * wildcard to match on a substring within the header value.

referer-whitelist

Include this behavior to allow (“whitelist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner.

Download schema: referer-whitelist-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "referer-whitelist",
            "value": "www.mysite.com www.myothersite.com*"
        }
    ]
}

referer-whitelist members

Member Type Required Description
referer-whitelist: Include this behavior to allow (“whitelist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner.
name Enumeration Enter referer-whitelist to allow access based on the Referer request header.
value String Enter a space-separated list of Referer header values to allow. Use the * wildcard to match on a substring within the header value.

site-failover

Include this behavior to define the alternate hostname and path to use when the edge server can’t contact the origin server.

Download schema: site-failover-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "site-failover",
            "type": "serve-301",
            "params": {
                "httpResponseStatus": "404 500:504",
                "alternateHostname": "www.mysite_failover.com",
                "alternatePath": "/failover/mysite",
                "preserveQueryString": true
            }
        }
    ]
}

site-failover members

Member Type Required Description
site-failover: Include this behavior to define the alternate hostname and path to use when the edge server can’t contact the origin server.
name Enumeration Enter site-failover to define an alternate response to serve when the edge server can’t contact the origin server.
params site-failover.params These are failover settings.
type Enumeration Select the failover action to use. Enter serve-301 for 301 redirects, serve-302 for 302 redirects, or serve-alternate to send a request to an alternate hostname and path.
site-failover.params: These are failover settings.
alternateHostname String Enter the domain of the hostname to failover to. Enter a dash (-) to use the original hostname when constructing the new URL.
alternatePath String Enter a valid URI path to failover to. Always include the initial slash. Include the closing slash to change the URL path but keep the original filename. Enter a dash (-) to use the original path when constructing the new URL.
httpResponseStatus String Enter a space-separated list of the HTTP status codes served to the client when site-failover is not in effect. You can use integer ranges (for example, 404, 500:504).
preserveQueryString Boolean Enter true to retain the query string from the original request URL, or enter false to remove the query string.

token-auth

Include this behavior to use tokens to control access to content. You can choose to transmit the token in a cookie, header, or query parameter.

Download schema: token-auth-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "token-auth",
            "value": "-",
            "type": "serve-301",
            "params": {
                "tokenName": "__mytoken__",
                "tokenDelimiter": "~",
                "aclDelimiter": "!",
                "hmacAlgorithm": "SHA256",
                "escapeTokenInputs": true,
                "ignoreQueryString": false,
                "key": "adf123",
                "transitionKey": "bce987",
                "salt": "worldnews175892"
            }
        }
    ]
}

token-auth members

Member Type Required Description
token-auth: Include this behavior to use tokens to control access to content. You can choose to transmit the token in a cookie, header, or query parameter.
name Enumeration Set to token-auth to use tokens to control access to content.
params token-auth.params Use these parameters to define how tokens are used by this behavior.
value String This is ignored for this match type, but required for consistency in the API. Set the value to a dash (-).
token-auth.params: Use these parameters to define how tokens are used by this behavior.
aclDelimiter String Specifies a single character to separate access control list (ACL) fields. You can’t use alphanumeric characters, or any of the following character class: [.&`=/:%]. If you don’t specify a value, ! is used as the delimiter.
escapeTokenInputs Boolean Set to true input values are escaped before adding them to the token.
hmacAlgorithm Enumeration Specifies the algorithm to use for the token’s hash-based message authentication code (HMAC) field. Valid entries are SHA256, SHA1, or MD5.
ignoreQueryString Boolean Set to true query strings are removed from a URL when computing the token’s HMAC algorithm.
key String Specifies an even number of hex digits for the token key. An entry can be up to 64 characters in length.
salt String Specifies a salt for use in the token. This can be a maximum of 250 characters, and it can’t use characters from the following class: [~@#%^&=/|\].
tokenDelimiter String Specifies a single character to separate the individual token fields. You can’t use characters from the following class: [a-zA-Z0-9=&/\:%]. If you don’t specify a value, ~ is used as the delimiter.
tokenName String Specifies the name of the token. Match the string on the following regular expression: ^([a-zA-Z_][a-zA-Z0-9-_]*)$.
transitionKey String Specifies an even number of hex digits for the token transition key. An entry can be up to 64 characters in length.

url-redirect

Include this behavior to configure redirect responses for specific client requests, and stop them from contacting the origin.

Download schema: url-redirect-behavior.json

Sample inclusion for this behavior in a PUT policy operation:

{
    "matches": [],
    "behaviors": [
        {
            "name": "url-redirect",
            "type": "301",
            "value": "-",
            "params": {
                "protocol": "request",
                "hostname": "request",
                "staticHostname": "www.somedomain.com",
                "subDomain": "music",
                "path": "request",
                "staticPath": "/abc",
                "pathPrefix": "/pre",
                "pathSuffix": "/su",
                "includeQueryString": true
            }
        }
    ]
}

url-redirect members

Member Type Required Description
url-redirect: Include this behavior to configure redirect responses for specific client requests, and stop them from contacting the origin.
name Enumeration Set url-redirect to define the URL used for a redirect client request.
params url-redirect.params These members are used to customize the URL used for the redirect.
type Integer Specifies the type of redirect sent to the client if the request meets the criteria set in the rule’s match. You can choose from 301 moved permanently, 302 found, 303 see other, or 307 temporary redirect.
value String This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (-).
url-redirect.params: These members are used to customize the URL used for the redirect.
hostname Enumeration This defines the destination hostname that should be used in the redirect URL. Allowed values include: static to apply a unique staticPath, addSubDomain to preface the hostname with a subDomain in the redirect request, replaceSubDomain to replace an existing subDomain value with one you specify, or request to use a subdomain already set in the client request.
includeQueryString Boolean When enabled, retains the query string on the redirect request. Defaults to true.
path Enumeration This defines how the redirect URL is constructed. Allowed values include: static to apply a fixed staticPath, addPrefix to preface the path in the client request with a pathPrefix, addSuffix to append a pathSuffix to the path in the client request, or request to only use the path provided in the client request.
pathIncludesFilename Boolean Include if path is set to staticPath. Indicates whether the path also includes the filename and extension for the redirect. Defaults to false.
pathPrefix String Include if path is set to addPrefix. Specifies the prefix to add to the path in a redirect request. For example, to redirect from the path /example.html to /baseball/example.html, set this to /baseball. You can’t use a single / to specify this path. A valid path is a / followed by at least one character.
pathSuffix String Include if path is set to addSuffix. The suffix to be added to the path in a redirect request. For example, to redirect from the path /example/index.html to /example/football/index.html, set this to /football. You can’t use a single / to specify this path. A valid path is a / followed by at least one character.
protocol Enumeration This defines the destination protocol to be used for the redirect URL. Allowed values include: HTTP to set the request to non-secure, HTTPS to set it to secure, or request to use the protocol set in the client request.
staticHostname String Include if hostname is set to static. Set this to the desired hostname for use in the redirect URL.
staticPath String Include if path is set to staticPath. Set this to a static path that should be used in the redirect URL. A valid path is a / followed by at least one character.
subDomain String Include if hostname is set to addSubDomain or replaceSubDomain. If set to addSubDomain, specify the subdomain to preface the existing domain. For example, to redirect from example.com to www.m.example.com set this value to www. If set to replaceSubDomain, set a value to replace an existing subdomain. Include a subdomain in the client request hostname, and only the first subdomain is replaced. For example, to change a redirect URL subdomain from domain.example.com or www.example.com to newdomain.example.com, set the value to newdomain.

Errors

This section shows you how to handle various kinds of errors this API generates, and lists the range of HTTP status codes along with their likely causes.

Error responses

The following example shows an error response for a request processed by this API:

{
    "errorCode" : 403,
    "message" : "Authorization failed",
    "description" : "The user is not authorized by Akamai Cloud Embed to access the policies or subcustomers assigned to the given property id.",
    "helpLink" : "https://developer.akamai.com/api/delivery-policies/errors.html#403",
    "errorInstanceId" : "31f1a7532f",
}

You would expect to see a message like this if the property ID is not valid or is not configured correctly.

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
202 Resource successfully accepted.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
408 Request timeout.
500 Internal server error.
503 Too many requests. Service is temporarily unavailable.

Last modified: 11/6/2019