Script Management API v1 - Akamai Documentation

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

Use the Script Management application to review the metrics and analysis.
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.
Form a policy object that contains the script actions and SPOF settings you want.
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.