Hello World using the EdgeWorkers API

Here's a high-level overview of the steps required to activate a code sample using the EdgeWorkers API.

For instructions on how to return detailed debugging information about your EdgeWorkers, go to the Enhanced debug headers section.

Refer to the comprehensive API documentation for a complete list of endpoints.

Step Description Details
1 You need to create an API client in Control Center for the EdgeWorkers service. To create an authentication token for the EdgeWorkers API, install the EdgeGrid plugin for HTTPie, then follow the steps in Get Started with APIs to learn how to configure authentication credentials.
2 Create a code bundle using the hello world code sample. Create the Hello World code bundle
3 Use the EdgeWorkers API to create and activate an EdgeWorker version. Activate the EdgeWorkers code bundle
4 Enable the EdgeWorkers behavior on specific Properties and define the match criteria and scope. Add the EdgeWorkers behavior to a Property
5 Test your EdgeWorkers function. Test the Hello World code sample

Create the Hello World code bundle

The EdgeWorkers code bundle must contain the main.js and bundle.json files.

Before you begin

Review the steps required to create an EdgeWorkers function.

How to

  1. Create a folder on your computer for the code bundle files.
  2. Go to the Akamai EdgeWorkers GitHub repository and download the main.js and bundle.json files from the helloworld project or create them using the values below.
  3. Use the Hello World code sample to create the JavaScript source in a file called main.js.
    // Hello World Example
    
    export function onClientRequest(request) {
      request.respondWith(
          200, {},
          '<html><body><h1>Hello World From Akamai EdgeWorkers</h1></body></html>');
    }
    
    export function onClientResponse(request, response) {
      response.setHeader('X-Hello-World', 'From Akamai EdgeWorkers');
    }
  4. Increment the edgeworker-version in the bundle.json file.
  5. Compress the files into a code bundle.
    tar -czvf filename.tgz main.js bundle.json

Activate the Hello World code bundle

Now that you've created the code bundle in the previous step, you can use HTTPie and httpie-edgegrid to access the Akamai APIs. The steps to deploy an EdgeWorker code bundle include: verifying the group identifier and permissions, uploading a new EdgeWorker version, and activating the EdgeWorker version.

Before you begin

Create the EdgeWorkers code bundle and make sure you have an authentication token for the EdgeWorkers API. Your administrator can create an API client in Control Center for the EdgeWorkers service. Make sure the <access token> is replaced with the OPEN APIs section from your .edgerc file.

How to

  1. Verify permissions and note the groupId for the group container being used. For more information on Groups and Permissions see Identity and Access Management help.
    http --timeout=30 --auth-type edgegrid -a <access token>: GET :/edgeworkers/v1/groups
    
    Note: If you don't see the groupId you were intending to add the EdgeWorker to or received an error the likely cause is the access token used does not have the proper permissions. Consult the Identity and Access Management Documentation or your Akamai Administrator.
  2. Create a new EdgeWorker Identifier.
    http --timeout=30 --auth-type edgegrid -a <access token>: POST :/edgeworkers/v1/ids groupId=<groupId> name=<name>

    <groupId> - group identifier for the EdgeWorker.

    <name> - name of the EdgeWorker. This name is the label used to select the EdgeWorker in the Property Manager behavior.  

    Note: To verify the EdgeWorker Identifier was created, try issuing the following API request.
     http --timeout=30 --auth-type edgegrid -a <access token>: GET :/edgeworkers/v1/ids groupId=<groupId>
    The Id created should be in the list of EdgeWorkers.
  3. Add a new version to the EdgeWorker Identifier.
    http --timeout=30 --auth-type edgegrid -a <access token>: POST :/edgeworkers/v1/ids/<edgeWorkerId>/versions Content-Type:application/gzip @<edgeworker code bundle>

    <edgeWorkerId> - EdgeWorker Identifier that contains the new version.  

    <edgeworker code bundle> - filename (as @/path/to/file) of the EdgeWorker code bundle containing the version update.

    Note: To verify the EdgeWorker version has been created, try issuing the following API request.
    http --timeout=30 --auth-type edgegrid -a <access token>: GET :/edgeworkers/v1/ids/<edgeWorkerId>/versions 
    The version just created should be contained in the list of versions.
  4. Activate the EdgeWorker version on the Akamai network. Note the activationId.
    http --timeout=30 --auth-type edgegrid -a <access token>: POST :/edgeworkers/v1/ids/<edgeWorkerId>/activations network=<network> version=<version>

    <edgeWorkerId>  - EdgeWorker Identifier that is being updated.

    <network>  - STAGING or PRODUCTION.

    <version> - Version Identifier for the version being activated.

    Note: To monitor the activation of the EdgeWorker version, try issuing the following API request.
    http --timeout=30 --auth-type edgegrid -a <access token>: GET :/edgeworkers/v1/ids/<edgeWorkerId>/activations/<activationId> 
    <edgeWorkerId> - EdgeWorker Identifier that is being updated.

    <activationId> - with the value received from activation response. The version just created should be contained in the list of versions.

Add the EdgeWorkers behavior to a Property

This section describes how your Akamai administrator can enable the EdgeWorkers behavior in Property Manager. This step can also be used to define which requests apply EdgeWorkers functions. By limiting the scope you can avoid unnecessary serverless hits to improve performance and reduce cost.

Before you begin

Make sure you have reviewed the prerequisites. To complete this an Akamai administrator will need to access the Akamai Control Center.

How to

  1. Navigate to your property in Control Center.
    You can use Property Manager to scope where and when to execute the EdgeWorker function.
  2. Click Edit.
  3. Click Add rule.
  4. Enter a name.
  5. Choose a match criteria and scope.
    Note: The criteria allows you to define which requests apply EdgeWorkers functions. By limiting the scope you can avoid unnecessary serverless hits.
  6. Search for EdgeWorkers in available behaviors.
  7. Change the setting to On.
  8. Click Insert Behavior.
  9. Select an EdgeWorker identifier from the list.
    If you haven't created an EdgeWorker identifier, click the link in the information dialog. The EdgeWorkers Management application will open in a new window.

    Once you have created your EdgeWorker identifier, close the window and reload the Property Manager Editor page. Now you can select the new EdgeWorker identifier from the list.
  10. Save your property.
  11. Click the Activate tab.
  12. Click the Activate v<#> on Staging or Activate v<#> on Production button.

Test the Hello World code sample

To test the Hello World code sample make a request to exercise the EdgeWorker and note the response.

Before you begin

Activate the Hello World code sample on your staging network.

How to

Use the following curl request, resolved to staging, to exercise the Hello World EdgeWorker.
For instructions on how to resolve an IP address refer to the Getting Started for HTTPS Properties documentation.
curl http://[your website name]/helloworld --resolve [your website name]:80:[your staging ip address]
The curl request should produce the following HTML output:
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 70
Date: Wed, 20 Nov 2019 17:09:17 GMT
Connection: keep-alive
X-Hello-World: From Akamai EdgeWorkers

<html><body><h1>Hello World From Akamai EdgeWorkers</h1></body></html>