akamai-edgegrid

EdgeGrid for Node.js

This library implements an Authentication handler for the Akamai EdgeGrid Authentication scheme in Node.js.

It’s Akamai’s current and officially supported version of AkamaiOPEN EdgeGrid for Node.js. You can find the most up-to-date package in NPM under akamai-edgegrid.

IMPORTANT: Akamai will not maintain the edgegrid package in NPM going forward.

Install

npm install --save akamai-edgegrid

Example

Credentials

Before you begin, you need to Create authentication credentials in Control Center.

.edgerc authentication

The preferred method of using the library involves providing the path to an .edgerc file. This file contains the authentication credentials used to sign your requests.

NOTE: Requests to the API are signed with a timestamp and are executed immediately.

var EdgeGrid = require('akamai-edgegrid');

var data = 'bodyData';

// Supply the path to your .edgerc file and name
// of the section with authorization to the client
// you are calling (default section is 'default')
var eg = new EdgeGrid({
  path: '/path/to/.edgerc',
  section: 'section-name'
});

eg.auth({
  path: '/diagnostic-tools/v1/locations',
  method: 'GET',
  headers: {},
  body: data
});

eg.send(function(error, response, body) {
  console.log(body);
});

An .edgerc file contains sections for each of your API client credentials and is usually hosted in your home directory:

[default]
host = akaa-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net/
client_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
client_secret = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
access_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
max-body = 131072

[section-name]
host = akaa-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net/
client_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
client_secret = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
access_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
max-body = 131072

Manual authentication

You can also authenticate manually by hard coding your credential values and passing them to the EdgeGrid client:

var clientToken = "akab-client-token-xxx-xxxxxxxxxxxxxxxx",
    clientSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    accessToken = "akab-access-token-xxx-xxxxxxxxxxxxxxxx",
    baseUri = "https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/";

var eg = new EdgeGrid(clientToken, clientSecret, accessToken, baseUri);

Chaining

You can also chain calls using the akamai-edgegrid like in this example:

...
eg.auth({
  path: '/papi/v1/groups',
  method: 'GET',
  headers: {},
}).send(function (error, response, body) {
  console.log(body);
});

This is an example of an API call to List groups in your property. Change the path element to reference an endpoint in any of the Akamai APIs.

Headers

Enter request headers as name-value pairs in an object.

NOTE: You don't need to include the Content-Type and Content-Length headers. The authentication layer adds these values.

eg.auth({
  path: '/papi/v1/groups',
  method: 'GET',
  headers: {
    'Accept': "application/json"
  }
});

Body data

You can provide the request body as either an object or as a POST data form string.

// Object
eg.auth({
    path: '/papi/v1/cpcodes?contractId=ctr_1234&groupId=grp_1234',
    method: 'POST',
    body: {
        cpcodeName: "test-cpcode",
        productId: "prd_Site_Accel"
    }
});

Query string parameters

When entering query parameters use the qs property under the auth method. Set up the parameters as name-value pairs in a object.

eg.auth({
    path: '/papi/v1/cpcodes',
    method: 'POST',
    headers: {},
    qs: {
        contractId: "ctr_1234",
        groupId: "grp_1234",
    },
    body: data
})

// Produces request URL similar to:
// https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/papi/v1/cpcodes?contractId=ctr_1234&groupId=grp_1234

Encoding

When interacting with binary data, such as during retrieval of PDF invoices, responseType should be specified as arraybuffer during the auth method call. Omission of responseType will cause an unreadable or blank response.

const fs = require('fs');

eg.auth({
  path : `/invoicing-api/v2/contracts/${contractId}/invoices/${invoiceNumber}/files/${fileName}`,
  method: 'GET',
  responseType: 'arraybuffer', // Important
}).send((err, response) => {
  if (err) {
    return console.log(err);
  }
  fs.writeFile(`./${fileName}`, response.data, 'binary', (err) => {
    if (err){
      return console.log(err);
    }
    console.log('File was saved!');
  });
});

Proxy

To use edgegrid with proxy, you can configure it with proxy field:

eg.auth({
  path : `/papi/v1/cpcodes`,
  method: 'GET',
  proxy: {
    host: 'my.proxy.com',
    protocol: "https",
    port: 3128,
    auth: {
      username: 'my-user',
      password: 'my-password'
    }
  }
}).send((err, response) => {
  if (err) {
    return console.log(err);
  }
  console.log('Success!');
  // Do something with response
});

or use environment variable:

$ export https_proxy=https://username:password@host:port
$ node myapp.js

Debug

With EdgeGrid you can enable debugging either as part of the EdgeGrid instantiation object or by setting the EG_VERBOSE environment variable. When enabled, EdgeGrid provides additional information about the request that's helpful for debugging.

Here's an EdgeGrid example:

// Set debug via EdgeGrid property
var eg = new EdgeGrid({
  path: edgercPath,
  section: sectionName,
  debug: true
});

And here's an example for a command-line argument:

// Set debug via environment variable
$ export EG_VERBOSE=true
$ node src/main.js

Starting Request {
  url: 'https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/papi/v1/groups',
  method: 'get',
  data: '',
  headers: {
    common: { Accept: 'application/json, text/plain, */*' },
    delete: {},
...
Response: {
  status: 200,
  statusText: 'OK',
  headers: {
    server: 'nginx',
    'content-type': 'application/json;charset=UTF-8',
...
}

Reporting issues

To report a problem or make a suggestion, create a new GitHub issue.

License

Copyright 2021 Akamai Technologies, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Changelog

3.5.1 (Sep 10, 2024)

IMPROVEMENTS:

• Updated various dependencies