Learn more:

• EdgeWorkers

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

Overview

The EdgeWorkers service lets you run JavaScript at the edge of the Internet to dynamically manage web traffic. You can use the EdgeWorkers API to deploy custom code on thousands of Akamai edge servers and apply logic that creates powerful web experiences.

Use the EdgeWorkers service to:

• Redirect requests based on geography, device, and user-agent.

• Apply conditional logic to filter requests and construct responses.

• Customize error responses to improve web experiences, even when the origin is down.

• Add or remove debug information from HTTP responses.

Get started

To use this API for the first time:

• Confirm that you have the entitlement for the EdgeWorkers service in your contract. EdgeWorkers is available for customers with Akamai ION and Dynamic Site Accelerator products.

• Review Get Started with APIs for instructions on setting up authentication 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, select the API service named EdgeWorkers, and choose READ-WRITE as the access level.

• Add a rule in Property Manager to enable the EdgeWorkers behavior. Follow the instructions in the User Guide

EdgeWorkers bundle format

To create the EdgeWorkers bundle, you need a JavaScript source file called main.js that contains event handler definitions for when to execute the code:

• onClientRequest. This event happens for every request as the request is received, before checking if a response is available in cache.

• onOriginRequest. This event happens just before sending the request to the origin.

• onOriginResponse. This event happens as the origin response is created.

• onClientResponse. This event happens for every request just before the client response is sent.

You also need to create a manifest file called bundle.json that includes meta information as described in the table below.

NOTE: For edgeworker-version limit characters to alphanumeric, underscore, dash, dot, and tilde.

{
    "edgeworker-version":"4.22.3",
    "bundle-version":1,
    "api-version":"0.3",
    "description":"Language Redirect",
    "misc":{
        "author":"jsmith",
        "git-commit":"4ce52c8ff4fdd1771e5347297ea5691b55c4f6ed",
        "updated":"2027-09-23"
    }
}

Resource limiting

This API imposes limits on some of the resources you can deploy. See Limitations in the EdgeWorkers User Guide.

Resources

Here are some terms and concepts that will help you understand how to use this API.

• ID: The EdgeWorkers API generates a unique edgeWorkerId, a numeric identifier that enables you to activate and manage your EdgeWorkers scripts.

• Group: Contains information about what EdgeWorker capabilities and permissions are allowed within the group.

• Version: A unique string value that enables you to track revision history for an edgeWorkerId. Each version refers to a specific bundle that contains your EdgeWorker script.

• Activation: EdgeWorkers code, identified by edgeWorkerId+version, set to execute on the Akamai staging or production network.

• Script Bundle: A collection of files including main.js, the JavaScript source that contains event handler functions, and bundle.json packaged together in a compressed .tgz file. See EdgeWorkers bundle format for details.

API summary

Download the RAML descriptors for this API.

List permission groups

View a list of groups and the associated permission capabilities, for example: activate a version or fetch an EdgeWorker ID.

{
    "groups": [
        {
            "groupId": 4284,
            "groupName": "Group #42",
            "capabilities": [
                "VIEW",
                "VIEW_VERSION",
                "VIEW_ACTIVATION",
                "ACTIVATE"
            ]
        },
        {
            "groupId": 109795,
            "groupName": "ESSL Behavior Tests",
            "capabilities": [
                "VIEW",
                "EDIT",
                "VIEW_VERSION",
                "CREATE_VERSION",
                "VIEW_ACTIVATION",
                "ACTIVATE"
            ]
        }
    ]
}

Get a permission group

View details on the capabilities enabled within a specified group, for example: activate a version or fetch an EdgeWorker ID.

{
    "groupId": 109795,
    "groupName": "ESSL Behavior Tests",
    "capabilities": [
        "VIEW",
        "VIEW_VERSION",
        "VIEW_ACTIVATION"
    ]
}

List EdgeWorker IDs

View the list of EdgeWorkers in the identified group.

{
    "edgeWorkerIds": [
        {
            "edgeWorkerId": 1,
            "name": "Ew_1",
            "accountId": "B-M-1KQK3WU",
            "groupId": 72297,
            "createdBy": "jsmith",
            "createdTime": "2018-10-15T14:49:40Z",
            "lastModifiedBy": "jsmith",
            "lastModifiedTime": "2018-10-15T15:21:15Z"
        },
        {
            "edgeWorkerId": 2,
            "name": "EdgeWorker #2",
            "accountId": "B-M-1KQK3WU",
            "groupId": 72297,
            "createdBy": "jsmith",
            "createdTime": "2018-10-15T16:54:40Z",
            "lastModifiedBy": "jsmith",
            "lastModifiedTime": "2018-10-15T16:54:40Z"
        }
    ]
}

Create a new EdgeWorker ID

Register a new EdgeWorker within a particular group.

{
    "groupId": 72297,
    "name": "Ew_42"
}

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42

{
    "edgeWorkerId": 42,
    "name": "Ew_42",
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}

Get an EdgeWorker

View details for a specific EdgeWorker.

{
    "edgeWorkerId": 42,
    "name": "Ew_1",
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}

Update an EdgeWorker

Update the name or groupId of an existing EdgeWorker.

{
    "groupId": 123456,
    "name": "New EdgeWorker Name"
}

{
    "edgeWorkerId": 42,
    "name": "New EdgeWorker Name",
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}

Validate an EdgeWorkers code bundle

Return a list of errors containing details on how to fix your code bundle. See Validation error types.

(Body specifies GZIP binary data.)

{
    "errors": [
        {
            "type": "STATIC_VALIDATION_FAILED",
            "message": "static validation failed : main.js::9:16 SyntaxError: Unexpected identifier."
        },
        {
            "type": "INVALID_MANIFEST",
            "message": "manifest file is invalid"
        }
    ]
}

List versions

View a list of EdgeWorker versions.

{
    "versions": [
        {
            "edgeWorkerId": 42,
            "version": 1,
            "accountId": "B-M-1KQK3WU",
            "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
            "createdBy": "jsmith",
            "createdTime": "2018-07-05T18:17:46Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 2,
            "accountId": "B-M-1KQK3WU",
            "checksum": "8277e0910d750195b448797616e091ad616e091a",
            "createdBy": "jsmith",
            "createdTime": "2018-07-05T23:01:34Z"
        }
    ]
}

Create a new version

Create a new version of an EdgeWorker.

(Body specifies GZIP binary data.)

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42/versions/5

{
    "edgeWorkerId": 42,
    "version": 5,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-05T18:17:46Z"
}

Get version details

View details for a specific version.

{
    "edgeWorkerId": 42,
    "version": 3,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-09T21:51:07Z"
}

Download an EdgeWorker bundle

Download the bundle containing the code the EdgeWorker executes.

(Body specifies GZIP binary data.)

List activations

View the list of activations for an existing EdgeWorker based on ID. You can choose to specify the version in the request.

{
    "activations": [
        {
            "edgeWorkerId": 42,
            "version": 2,
            "activationId": 3,
            "accountId": "B-M-1KQK3WU",
            "status": "PENDING",
            "network": "PRODUCTION",
            "createdBy": "jdoe",
            "createdTime": "2018-07-09T09:03:28Z",
            "lastModifiedTime": "2018-07-09T09:04:42Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 1,
            "activationId": 1,
            "accountId": "B-M-1KQK3WU",
            "status": "IN_PROGRESS",
            "network": "STAGING",
            "createdBy": "jsmith",
            "createdTime": "2018-07-09T08:13:54Z",
            "lastModifiedTime": "2018-07-09T08:35:02Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 2,
            "activationId": 2,
            "accountId": "B-M-1KQK3WU",
            "status": "COMPLETE",
            "network": "PRODUCTION",
            "createdBy": "asmith",
            "createdTime": "2018-07-10T14:23:42Z",
            "lastModifiedTime": "2018-07-10T14:53:25Z"
        }
    ]
}

Activate an EdgeWorker version

Activate an existing EdgeWorker version on the Akamai network, either staging or production.

{
    "network": "PRODUCTION",
    "version": 2
}

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42/activations/3

{
    "edgeWorkerId": 42,
    "version": 5,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PRESUBMIT",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2019-04-05T18:17:46Z",
    "lastModifiedTime": "2019-04-05T18:17:46Z"
}

Get an activation

View details for a specific activation.

{
    "edgeWorkerId": 42,
    "version": 9,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}

Data

This section details each type of data object that the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Permissions

This section describes EdgeWorker capabilities allowed within the Akamai group.

Download schema: group.json

Sample GET response:

{
    "groupId": 109795,
    "groupName": "ESSL Behavior Tests",
    "capabilities": [
        "VIEW",
        "VIEW_VERSION",
        "VIEW_ACTIVATION"
    ]
}

Permissions members

EdgeWorker

Attributes of an EdgeWorker.

Download schema: id-put-request.json, id.json

Sample POST request:

{
    "groupId": 72297,
    "name": "Ew_42"
}

EdgeWorker members

Validation

Provides details for an EdgeWorker code bundle validation.

Download schema: validation.json

Sample POST request:

{
    "errors": [
        {
            "type": "STATIC_VALIDATION_FAILED",
            "message": "static validation failed : main.js::9:16 SyntaxError: Unexpected identifier."
        },
        {
            "type": "INVALID_MANIFEST",
            "message": "manifest file is invalid"
        }
    ]
}

Validation members

Version

Provides details for an EdgeWorker version.

Download schema: version.json

Sample POST request:

{
    "edgeWorkerId": 42,
    "version": 5,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-05T18:17:46Z"
}

Version members

Activation

Information required to create an EdgeWorker activation.

Download schema: activations-post-request.json, activation.json

Sample POST request:

{
    "network": "PRODUCTION",
    "version": 2
}

Sample GET response:

{
    "edgeWorkerId": 42,
    "version": 9,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}

Activation members

Errors

This section details the API’s common responses to error cases. You’ll find the API’s range of response status codes for both error and success cases.

Validation error types

This table provides details for each validation error type.

Error responses

This API adheres to the Problem Details for HTTP APIs standard, and returns detailed error responses, such as:

{
    "type": "/edgeworkers/error-types/edgeworkers-invalid-argument",
    "title": "Invalid Argument.",
    "detail": "Invalid tarball provided",
    "instance": "/devpops-api/error-instances/1fb2b105-e976-4e28-ba26-fa649a0d86ff",
    "status": 400
}

HTTP status codes

This section lists the full range of response codes the API may generate.