Script Management API v1

A suite of tools to help you minimize performance impacts from JavaScripts. Use this API to retrieve or create Script Management policies.

Learn more:


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

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

Operation Method Endpoint
Get a policy GET /script-management/api/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies
Create a policy POST /script-management/api/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies

Get a policy

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

GET /script-management/api/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies

Sample: /script-management/api/v1/properties/226116/hostnames/www.example.com/network/staging/policies

Parameter Type Sample Description
URL parameters
propertyId Number 226116 A unique identifier for a property. ID values for all your properties are available from the Property Manager API’s List Properties operation.
hostname String www.example.com The property hostname whose policy you want to read or write.
network Enumeration staging The network whose policy you want to read or write, either staging or production.

Status 200 application/json

Response Body:

[
    {
        "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.

POST /script-management/api/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies

Sample: /script-management/api/v1/properties/226116/hostnames/www.example.com/network/staging/policies

Content-Type: application/json

Request Body:

{
    "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"
}
Parameter Type Sample Description
URL parameters
propertyId Number 226116 A unique identifier for a property. ID values for all your properties are available from the Property Manager API’s List Properties operation.
hostname String www.example.com The property hostname whose policy you want to read or write.
network Enumeration staging The network whose policy you want to read or write, either staging or production.

Status 201 application/json

Response Body:

{
    "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:

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.

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

Member Type Required Description
activationTime String Read-only. An ISO–8601 timestamp representing when the customer last modified the policy.
policyNote String Comments to aid in distinguishing policy versions.
scriptConfig Policy.scriptConfig[] Encapsulates a set of actions applied either to an individual script or a group of related scripts. Each policy needs at least one scriptConfig item or spofConfig.
spofConfig Policy.spofConfig Encapsulates settings for Single-Point-of-Failure (SPOF) Protection, which moves a call for a script to the background if it takes too long to load. The timeout value adjusts automatically in response to network conditions. Each policy needs a spofConfig or at least one scriptConfig array item.
versionId String Read-only. A unique identifier indicating the version of the policy.
Policy.scriptConfig[]: Encapsulates a set of actions applied either to an individual script or a group of related scripts. Each policy needs at least one scriptConfig item or spofConfig.
action Enumeration How Script Management handles the specified script. A value of DEFER executes the script after the page load event. BLOCK prevents the script from loading entirely. NO_ACTION loads the script normally.
item String Specifies the fully qualified URL for the script on which to perform the action.
type Enumeration Indicates that the item receiving the action is the URL for an individual script.
Policy.spofConfig: Encapsulates settings for Single-Point-of-Failure (SPOF) Protection, which moves a call for a script to the background if it takes too long to load. The timeout value adjusts automatically in response to network conditions. Each policy needs a spofConfig or at least one scriptConfig array item.
advancedSettings Policy.spofConfig.advancedSettings Encapsulates settings that control the upper and lower limits of the timeout range.
spofEnabled Boolean Enables SPOF Protection.
Policy.spofConfig.advancedSettings: Encapsulates settings that control the upper and lower limits of the timeout range.
maxSpofTimeoutInSecs Number Upper limit of SPOF Protection timeout range in seconds.
minSpofTimeoutInSecs Number Lower limit of SPOF Protection timeout range in seconds.

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.

Code Description
200 The operation was successful.
201 Policy successfully created.
400 Bad argument or value.
403 Forbidden.
404 Policy not found.
409 Policy already exists with the same scriptConfig and spofConfig.
500 Internal server error.

Last modified: 11/1/2018