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. The API also provides a set of accompanying insights about how scripts covered by existing policies execute. 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, enable the Script Management behavior. 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 insights, 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.

Operation Method Endpoint
Policies  
Get a policy GET /script-management/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies
Create a policy POST /script-management/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies
Insights  
Get Insights GET /script-management/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/insights{?firstParty,thirdParty}

Get a policy

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

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

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

Parameter Type Sample Description
URL path 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

Object type: Policy

Download schema: policies-get.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/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/policies

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

Content-Type: application/json

Object type: Policy

Download schema: policies-request.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 path 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

Object type: Policy

Download schema: policies-request.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"
}

Get insights

Returns insights information for the specified property, hostname, and network.

GET /script-management/v1/properties/{propertyId}/hostnames/{hostname}/network/{network}/insights{?firstParty,thirdParty}

Sample: /script-management/v1/properties/226116/hostnames/www.example.com/network/staging/insights?firstParty=false&thirdParty=false

Parameter Type Sample Description
URL path 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 insights information you want to read.
network Enumeration staging The network whose insights information you want to read, either STAGING, PRODUCTION, or BOTH.
Optional query parameters
firstParty Boolean false Filter to include only first party scripts, true by default.
thirdParty Boolean false Filter to include only third party scripts, true by default.

Status 200 application/json

Object type: Insight

Download schema: insights-get.json

Response body:

{
    "staging": [
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/block.php.js",
            "party": "THIRD_PARTY",
            "spof": true,
            "recentPopularityPercentage": 1,
            "minPopularityPercentage": 1,
            "avgPopularityPercentage": 1,
            "maxPopularityPercentage": 2,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 461,
            "avgTransferSizeBytes": 476,
            "maxTransferSizeBytes": 514,
            "recentTransferTimeMs": 10285,
            "minTransferTimeMs": 9654,
            "avgTransferTimeMs": 10336,
            "maxTransferTimeMs": 10914,
            "analysis": "HIGH",
            "action": "BLOCK",
            "analysisReason": "Slow transfer time (>1000 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        },
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/defer.php.js",
            "party": "THIRD_PARTY",
            "spof": false,
            "recentPopularityPercentage": 100,
            "minPopularityPercentage": 100,
            "avgPopularityPercentage": 100,
            "maxPopularityPercentage": 100,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 458,
            "avgTransferSizeBytes": 474,
            "maxTransferSizeBytes": 512,
            "recentTransferTimeMs": 29,
            "minTransferTimeMs": 27,
            "avgTransferTimeMs": 31,
            "maxTransferTimeMs": 44,
            "analysis": "LOW",
            "action": "DEFER",
            "analysisReason": "Fast transfer time (<300 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        }
    ],
    "production": [
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/block.php.js",
            "party": "THIRD_PARTY",
            "spof": true,
            "recentPopularityPercentage": 1,
            "minPopularityPercentage": 1,
            "avgPopularityPercentage": 1,
            "maxPopularityPercentage": 2,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 461,
            "avgTransferSizeBytes": 476,
            "maxTransferSizeBytes": 514,
            "recentTransferTimeMs": 10285,
            "minTransferTimeMs": 9654,
            "avgTransferTimeMs": 10336,
            "maxTransferTimeMs": 10914,
            "analysis": "HIGH",
            "action": "BLOCK",
            "analysisReason": "Slow transfer time (>1000 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        },
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/defer.php.js",
            "party": "THIRD_PARTY",
            "spof": false,
            "recentPopularityPercentage": 100,
            "minPopularityPercentage": 100,
            "avgPopularityPercentage": 100,
            "maxPopularityPercentage": 100,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 458,
            "avgTransferSizeBytes": 474,
            "maxTransferSizeBytes": 512,
            "recentTransferTimeMs": 29,
            "minTransferTimeMs": 27,
            "avgTransferTimeMs": 31,
            "maxTransferTimeMs": 44,
            "analysis": "LOW",
            "action": "DEFER",
            "analysisReason": "Fast transfer time (<300 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        }
    ]
}

Data

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

Download the JSON schemas for this API.

This section’s data schema tables 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
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.
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.

Insight

Collects metrics about each script’s performance. The top-level response object includes separate arrays for scripts running on the STAGING and PRODUCTION networks.

Download schema: script-view.json

Sample GET response:

{
    "staging": [
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/block.php.js",
            "party": "THIRD_PARTY",
            "spof": true,
            "recentPopularityPercentage": 1,
            "minPopularityPercentage": 1,
            "avgPopularityPercentage": 1,
            "maxPopularityPercentage": 2,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 461,
            "avgTransferSizeBytes": 476,
            "maxTransferSizeBytes": 514,
            "recentTransferTimeMs": 10285,
            "minTransferTimeMs": 9654,
            "avgTransferTimeMs": 10336,
            "maxTransferTimeMs": 10914,
            "analysis": "HIGH",
            "action": "BLOCK",
            "analysisReason": "Slow transfer time (>1000 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        },
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/defer.php.js",
            "party": "THIRD_PARTY",
            "spof": false,
            "recentPopularityPercentage": 100,
            "minPopularityPercentage": 100,
            "avgPopularityPercentage": 100,
            "maxPopularityPercentage": 100,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 458,
            "avgTransferSizeBytes": 474,
            "maxTransferSizeBytes": 512,
            "recentTransferTimeMs": 29,
            "minTransferTimeMs": 27,
            "avgTransferTimeMs": 31,
            "maxTransferTimeMs": 44,
            "analysis": "LOW",
            "action": "DEFER",
            "analysisReason": "Fast transfer time (<300 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        }
    ],
    "production": [
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/block.php.js",
            "party": "THIRD_PARTY",
            "spof": true,
            "recentPopularityPercentage": 1,
            "minPopularityPercentage": 1,
            "avgPopularityPercentage": 1,
            "maxPopularityPercentage": 2,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 461,
            "avgTransferSizeBytes": 476,
            "maxTransferSizeBytes": 514,
            "recentTransferTimeMs": 10285,
            "minTransferTimeMs": 9654,
            "avgTransferTimeMs": 10336,
            "maxTransferTimeMs": 10914,
            "analysis": "HIGH",
            "action": "BLOCK",
            "analysisReason": "Slow transfer time (>1000 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        },
        {
            "category": "Miscellaneous",
            "group": "renegade.akalab.ca",
            "script": "https://renegade.akalab.ca/edge-demo/defer.php.js",
            "party": "THIRD_PARTY",
            "spof": false,
            "recentPopularityPercentage": 100,
            "minPopularityPercentage": 100,
            "avgPopularityPercentage": 100,
            "maxPopularityPercentage": 100,
            "recentTransferSizeBytes": 487,
            "minTransferSizeBytes": 458,
            "avgTransferSizeBytes": 474,
            "maxTransferSizeBytes": 512,
            "recentTransferTimeMs": 29,
            "minTransferTimeMs": 27,
            "avgTransferTimeMs": 31,
            "maxTransferTimeMs": 44,
            "analysis": "LOW",
            "action": "DEFER",
            "analysisReason": "Fast transfer time (<300 ms)",
            "testingSuggestions": [
                "https://www.maple-af.com/"
            ]
        }
    ]
}

Insight members

Member Type Description
Insight: Collects metrics about each script’s performance. The top-level response object includes separate arrays for scripts running on the STAGING and PRODUCTION networks.
action Enumeration The action taken on the script, either DEFER, BLOCKED, NO_ACTION_LOCKED, or NO_ACTION. 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. NO_ACTION_LOCKED indicates either the script can’t be blocked or deferred, to ensure the script functions properly, or it’s required for Script Management functionality, such as when running the MPulse script.
analysis Enumeration An estimate of a script’s possible impact according to Script Management’s algorithms. HIGH indicate scripts that slow page loading significantly. MEDIUM indicate scripts that have less impact. Scripts with LOW analysis are of least concern.
analysisReason String Describes the reason for analysis.
avgPopularityPercentage Integer The mean popularity value from previous insights within a one month period, including the current analysis.
avgTransferSizeBytes Integer The mean transfer size from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
avgTransferTimeMs Integer The mean transfer time from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
category String For THIRD_PARTY scripts, the type of functionality that this script or group provides. For example, Analytics, Advertising, or Security. For FIRST_PARTY scripts, the category is the domain where the script or group resides.
group String For THIRD_PARTY scripts, a set of scripts with shared functionality. Typically, the scripts in a group are part of the same application. For FIRST_PARTY scripts, the group is the hostname where the scripts reside.
maxPopularityPercentage Integer The maximum popularity value from previous insights within a one month period, including the current analysis.
maxTransferSizeBytes Integer The maximum transfer size from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
maxTransferTimeMs Integer The maximum transfer time from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
minPopularityPercentage Integer The minimum popularity value from previous insights within a one month period, including the current analysis.
minTransferSizeBytes Integer The minimum transfer size from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
minTransferTimeMs Integer The minimum transfer time from previous insights within a one month period, including the current analysis. A value of zero means that the script is cached in the user’s browser.
party Enumeration Whether the script or group resides are hosted on this policy’s hostname (FIRST_PARTY) or a different hostname (THIRD_PARTY).
recentPopularityPercentage Integer The percentage of beacons that included a reference to this script. The higher the value, the more of your users the script impacts.
recentTransferSizeBytes Integer The transfer size of the script resource. If the script is compressed for transfer, this reflects the compressed size, not the extracted size. The value is displayed in KBs if the number of bytes is greater than 1024. If the script size is less than 1024 bytes, it is shown in bytes. The value Cached indicates that the script is cached in the user’s browser and so no transfer was required.
recentTransferTimeMs Integer The average time, in milliseconds, it took for the script to transfer once requested. A value of zero indicates that the script is cached in the user’s browser and so no transfer was required.
script String URL of the script.
spof Boolean If Single-Point-of-Failure (SPOF) Protection is enabled or disabled.
testingSuggestions Array Fully qualified URL of pages on your site that reference the selected script. This is not a complete list, but shows only the five pages with the most beacons referencing the script.

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.