Learn more:

• Script Management online help

• Download this API’s RAML and JSON schema descriptors.

Overview

The Script Management API allows you to retrieve and create Script Management policies. With a policy, you can specify which scripts to block or defer automatically and enable SPOF Protection on your site. This can help minimize performance impacts from JavaScripts.

Single-Point-of-Failure (SPOF) Protection moves a call for a script to the background if it impacts page loading. SPOF Protection intervenes when a script exceeds a timeout value, which adjusts automatically in response to network conditions. SPOF Protection applies only to third-party scripts.

This API is a companion to the Script Management application in Akamai Control Center. The Script Management application includes metrics and analysis that show you which scripts on your site are causing the large set impacts to performance. You should review the information in the Script Management dashboard before creating any Script Management policies.

The Script Management application also includes testing suggestions to help you find the most popular pages that your policies affect, so you can confirm that Script Management is working as intended.

Several of the operations currently possible only in the Script Management application will likely be added in a future release of this API.

Script Management depends on mPulse as its source for metrics about script performance on your site.

You typically use the Script Management API to retrieve a policy created for one hostname and apply it to many other hostnames on your property.

To learn more about setting up and using Script Management, refer to the Script Management online help and the Script Management topics in the Property Manager online help. To learn more about mPulse, refer to the mPulse documentation.

Get started

To configure this API for the first time:

• 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 Script Management, and set the access level to READ-WRITE.

• Enable mPulse, following the mPulse Quick Start instructions, with one exception: You cannot tag your site’s pages with the mPulse snippet on your origin, either manually or with a tag manager. The snippet must be injected at the edge servers. Use the standard configuration instructions to accomplish this.

• In your Property Manager configuration, add the Script Management behavior and enable it. Continue with activating on staging, testing, and activating on production. If you just enabled mPulse on your property, allow some time for data collection before continuing.

• Use the Property Manager API (PAPI) if you want to programmatically access all your properties and the hostnames to which they apply.

• Access the Script Management application, and review metrics and analysis for scripts on your site. This information can help you decide what actions you want to include in your Scrip Management policies. See the Script Management online help for detailed instructions.

Resources

Use the Script Management API to retrieve existing policies and create new policies. Each policy is specific to a particular hostname and property. When you enable Script Management as described in Get started, Script Management creates a policy for each hostname configured on your property.

These initial policies do not contain any block or defer actions. However, they do turn on the Script Management service worker and apply Single-Point-of-Failure (SPOF) Protection to hostnames on your property.

Each policy has two versions: one for the staging network and one for production. When you create a policy, it overrides the existing policy for the network where you create it.

This sample workflow describes a process for applying one policy to all hostnames on your property:

1. Use the Script Management application to review the metrics and analysis.

2. Use the Script Management Policy Tester to experiment locally. Determine what scripts you want to block and defer, and decide the optimal range for SPOF Protection timeout.

3. Form a policy object that contains the script actions and SPOF settings you want.

4. Run the Create a policy POST operation to create a policy on staging using those same actions and SPOF settings, iterating through all hostnames on your property. To accomplish this programmatically, use the Property Manager API’s List a property’s hostnames operation.

API summary

Download the RAML descriptors for this API.

Get a policy

Returns information about the latest version of a policy for the specified property, hostname, and network.

[
    {
        "versionId": "1",
        "activationTime": "2018-02-19T09:45:00.000Z",
        "scriptConfig": [
            {
                "item": "https://www.example.com/main.min.js",
                "type": "URL",
                "action": "BLOCK"
            },
            {
                "item": "https://www.example.com/analytics.js",
                "type": "URL",
                "action": "DEFER"
            }
        ],
        "spofConfig": {
            "spofEnabled": true,
            "advancedSettings": {
                "minSpofTimeoutInSecs": 6,
                "maxSpofTimeoutInSecs": 20
            }
        },
        "policyNote": "First version for testing"
    }
]

Create a policy

Creates a new policy by overwriting the existing policy for the specified property, hostname, and network. The Policy request must include at least one spofConfig object or scriptConfig array item. If a policy already exists with the same spofConfig and scriptConfig, the API responds with a 409 error that contains data for the existing policy.

{
    "scriptConfig": [
        {
            "item": "https://www.example.com/main.min.js",
            "type": "URL",
            "action": "BLOCK"
        },
        {
            "item": "https://www.example.com/analytics.js",
            "type": "URL",
            "action": "DEFER"
        }
    ],
    "spofConfig": {
        "spofEnabled": true,
        "advancedSettings": {
            "minSpofTimeoutInSecs": 6,
            "maxSpofTimeoutInSecs": 20
        }
    },
    "policyNote": "First version for testing"
}

{
    "versionId": "1",
    "activationTime": "2018-02-19T09:45:00.000Z",
    "scriptConfig": [
        {
            "item": "https://www.example.com/main.min.js",
            "type": "URL",
            "action": "BLOCK"
        },
        {
            "item": "https://www.example.com/analytics.js",
            "type": "URL",
            "action": "DEFER"
        }
    ],
    "spofConfig": {
        "spofEnabled": true,
        "advancedSettings": {
            "minSpofTimeoutInSecs": 6,
            "maxSpofTimeoutInSecs": 20
        }
    },
    "policyNote": "First version for testing"
}

Data

This section describes the Script Management API’s data structures.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Policy

The policy object includes information about which scripts or groups to manage, what action to apply to each defer or block and what SPOF settings to apply.

Download schema: policies-request.json

Sample GET response:

[
    {
        "versionId": "1",
        "activationTime": "2018-02-19T09:45:00.000Z",
        "scriptConfig": [
            {
                "item": "https://www.example.com/main.min.js",
                "type": "URL",
                "action": "BLOCK"
            },
            {
                "item": "https://www.example.com/analytics.js",
                "type": "URL",
                "action": "DEFER"
            }
        ],
        "spofConfig": {
            "spofEnabled": true,
            "advancedSettings": {
                "minSpofTimeoutInSecs": 6,
                "maxSpofTimeoutInSecs": 20
            }
        },
        "policyNote": "First version for testing"
    }
]

Policy members

Errors

This section describes the range of responses that the Script Management API can generate. The descriptions of error codes can assist with debugging.

If you receive a 500 error, try using the Script Management application to perform the action instead.

Error responses

The API generates JSON error objects, like the one shown below. The Script Management API error objects adhere to the HTTP Problem Details standard.

{
    "httpStatus": 400,
    "type": "/script-management/error-types/bad-request",
    "title": "/script-management/error-types/bad-request",
    "detail": "Bad Argument or Value",
    "instance": "30d08511-f6ad-4fa8-8bf4-109064817277",
    "errors": [
        {
            "detail": "minimumSPOFTimeout 5 should not exceed maximumSPOFTimeout 4",
            "maximumSPOFTimeoutInSecs": 4,
            "minimumSPOFTimeoutInSecs": 5
        }
    ]
}

HTTP status codes

This section lists the full range of response codes that the Script Management API can generate. Refer to these descriptions for assistance with debugging.

Last modified: 1/7/2019