Jeffrey Costa

Using Postman to access Akamai {OPEN} APIs

Blog Post created by Jeffrey Costa Employee on Dec 22, 2017

Akamai uses a signature pattern called EdgeGrid in our OPEN APIs for added authentication security. It ensures that a compromised API request (ex: one that is altered and later replayed) cannot have a catastrophic impact on the platform. But it also adds complexity to making API requests that can seem rather intimidating to new users.

 

To overcome this problem, Akamai creates and maintains several EdgeGrid clients in many popular programming languages in our GitHub repo that may be downloaded and customized. These provide a jumpstart to using our APIs in applications our customers write. But sometimes you just need to make a simple API request and get a response without writing code or using cURL at the command line. That's where Postman comes in. Postman is a popular, free GUI tool with a sleek user interface with which to make API requests without the hassle of writing a bunch of code just to test an API's functionality.

 

Postman is the de-facto GUI tool API developers use today for its purpose-built capabilities of viewing requests and responses, running mocks and automated tests, and saving API calls in collections for reuse and sharing.  You can download a free version for Mac or Windows here. Do not download the Chrome plugin version, as it will shortly be reaching end-of-life. This tutorial will show you how to use Postman to access Akamai's APIs, and assumes you already installed Postman, and have a limited working knowledge of how to use it.

 

This process we will follow to get this working uses the credentials you obtain from Luna to build a so-called "Environment" in Postman. This environment will supply the necessary Luna credentials to a "pre-request script" (written in Javascript) that executes ahead of your request, producing all the necessary headers that Akamai's OPEN APIs require for access. There is nothing you need to change or modify in the Javascript; everything is done for you. 

 

Before beginning this process, you will need a set of credentials that are generated through Luna. This is done by browsing to the Configure -> Manage APIs -> Identity Management section of the Luna portal. It is beyond the scope of this article to provide these instructions, but a walkthru may be found here. The process includes setting authorizations needed to access the endpoint. Luna will provide you with the four pieces of credential and authorization information that you need to copy down: Client Token, Client Secret, Base URL, and Access Token. Ensure that you save these values in a text file somewhere, as you will need to copy/paste them into Postman later. For reference, this is a sample of what credentials look like in Luna:

 

 

Now launch Postman and open a new tab. In that tab, enter the Base URL value you copied from Luna PLUS the endpoint you wish to access. For example, I want to make a request the API-Endpoints API, which would look like this:
https://akab-hwf3jy2loh42cuew-u4av3vqrtuagzznk.luna.akamaiapis.net/api-definitions/v2/endpoints 

 

You will likely want to save the work you are doing in a Postman collection for later use. With the request URL entered, take a moment and click the "Save" button near the right side of the interface. In the screenshot below, I am naming my new request "Rapid API" and saving it to an existing collection I have called "Akamai OPEN."

 

You can name the request and the collection anything you like. If you do not have an existing collection, simply click the "+ Create Folder" link to create a new folder to house your collection of requests. Now that we have the request saved, lets continue to edit it. Click on the "Headers" tab and enter a new HTTP header in key-value pair format. The name of the header should be "Authorization" and the value should be this variable: {{authorizationHeader}} 

 

If you typed it in correctly, it should look like this:


The variable is empty right now, but once we fill it, hovering over it will reveal a truncated popup showing the values that will be sent:

 

Now that we have the URL and the request headers steps done, we must setup two other Postman features to ensure our request goes through: a "Pre-Request Script" and an "Environment." Lets tackle the Environment first.

 

Environments let you customize requests using name-value pair variables that are used when you switch between different development environments, negating the need to change your API request itself. This lets you more easily make requests to different API environments such as a local machine, a development server, and a production API and pass in the correct information to those APIs. You may find a detailed walkthrough on setting this feature up in the Postman documentation if you want additional details.

 

For our purposes, a script we will be using will be extracting your OPEN credential information out of the Environment variables. To set this up, click on the cog icon in the upper-right corner of the Postman interface, and click on "Manage Environments:"

 

A modal dialog box will popup and overlay the Postman interface. Click the orange "Add" button to add a new environment. Give the environment a unique name (in my example below, I call it "Akamai OPEN APIs"), then start adding the key-value pairs that you copied from Luna, one at a time. Each one should be a separate name-value pair on a unique line, like this:

 

Be sure to use the exact names of the token and key values shown above. A script we will configure in a moment will be looking for these exact values, so be sure to duplicate the key value names correctly. Also note that the baseURL entry DOES NOT have an http/https protocol prefix added to it - only the domain name. BaseURL is analogous to hostname, so don't let that term confuse you. Save and close this window once you have input each of the four name-value pairs.

 

After you create the environment, click on the dropdown window to the left of the cog icon and select the environment you just created. This ensures the environment is now active for the request (which it must be). If it is NOT active, Postman will show a "No Environment" message by default. 

Finally, we need to configure what Postman calls a "Pre-Request Script," which is a powerful way of enhancing HTTP calls with custom Javascript that is executed before a request is sent. This will be used to craft the custom HTTP headers that the Akamai EdgeGrid system requires. To enable this functionality, click on the "Pre-request Script" section of the interface to the right of the Headers and Body entries. You will then copy and paste the Javascript code (downloadable below) into the text box that appears:

 

Now save the request to capture all of these changes. Your configuration is now complete, and you may now click the "Send" button to send or retrieve data from an Akamai API. In the example below, I am GET'ing data about an API Endpoint that I previously configured on Akamai. Credential names have been blurred to protect the innocent, but you can clearly see the response coming in from the Edge server:

 

That is all it takes! If you want to make a different request to the API, the fastest way is to use the "Duplicate" functionality of the saved request in your collection to make a copy. Right-click on the existing request and select "Duplicate"

This will pre-populate a new request with the same values as the old one. You may then customize it with any endpoints or other characteristics you wish for the new request. This saves alot of typing and extra work recreating requests.

 

This process should enable you to work with any OPEN API. As another example, here is a Postman request and response made to the Property Manager API.

 

Happy Postman'ing! 

 

(Note: this tutorial was derived from one created earlier this year by another Akamai employee. I stood on the shoulders of giants (Seungheun Noh).

Attachments

Outcomes