
Learn more:
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/ |
Create a policy | POST | /script-management/ |
Insights | ||
Get Insights | GET | /script-management/ |
Get a policy
Returns information about the latest version of a policy for the specified property, hostname, and network.
GET /script-management/
Sample: /script-management/
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/
Sample: /script-management/
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/
Sample: /script-management/
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. |
○ | 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. |
○ | 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. |
✓ | 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. |
|||
max |
Number | ✓ | Upper limit of SPOF Protection timeout range in seconds. |
min |
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. |
avg |
Integer | The mean popularity value from previous insights within a one month period, including the current analysis. |
avg |
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. |
avg |
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. |
max |
Integer | The maximum popularity value from previous insights within a one month period, including the current analysis. |
max |
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. |
max |
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. |
min |
Integer | The minimum popularity value from previous insights within a one month period, including the current analysis. |
min |
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. |
min |
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 ). |
recent |
Integer | The percentage of beacons that included a reference to this script. The higher the value, the more of your users the script impacts. |
recent |
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. |
recent |
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. |
testing |
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. |