Get Started with APIs

Create credentials in Control Center and make API calls over the Akamai network.

Akamai offers a rich library of APIs that you can use to manage your Akamai solutions. Whether you want to make configuration changes or retrieve the latest security events, you can execute these requests more easily than you might think.

This guide gets you up and running with an environment to interact with Akamai APIs.

Get some specifics for your API

Before you start, you need a few things specific to your API:

  • Get the Akamai product added to your contract. Each API typically corresponds with a specific Akamai product. Work with your Akamai account rep to get this done.

  • Get the API service’s name.

  • Determine the level of access you’ll need to work with the API. This can be READ-WRITE, READ-ONLY, or ADMIN.

You can find this info in the Get started section of each Akamai API doc. See all Akamai API docs.

Authentication with EdgeGrid

You need to properly authenticate your API requests, whether they’re made directly to an API endpoint or through a request tool that wraps API requests. Akamai uses a proprietary authentication system called EdgeGrid for APIs deployed through Akamai Control Center.

Set up permissions

You use Control Center to set up this authentication and you need the correct roles and permissions on your account. Talk to the Akamai administrator in your organization, or contact your Akamai account rep to get both of these Identity and Access Management permissions set in your role:

  • IDM: API Clients - User Access
  • IDM: API Clients - Admin Access

Set up authentication for an API client

This quickly creates an API client with the necessary credential for a single Control Center account. This credential applies to all APIs for all products you currently have access to with that Control Center account.

Note: If you need to create a client to manage multiple Control Center accounts, see Manage many accounts with one client.

  1. Launch Identity and Access Management. In Control Center, you can navigate there by selecting ACCOUNT ADMINIdentity & access.

  2. From the Users and API Clients tab, click Create API client, then select Myself under Select API client type.

    Note: If you don’t have access to the Identity and Access Management tool, you don’t see the Create API client option, or you don’t see the Myself option, contact your local admin or your Akamai account rep for assistance.

  3. Click Quick to instantly create an API client with the necessary credential. This client’s API access levels, group roles, and permissions are identical to your current login.

  4. You can verify the APIs you can access by clicking Show additional details. Enter the API service’s name in the Filter field to verify that it’s included and that you have the proper level of access. If it’s missing, or the wrong level of access is set, contact your local administrator or your Akamai account rep.

  5. Click Hide additional details to return to the Details and Credentials information.

  6. Keep the API client for you page open. You’ll need the information displayed here throughout the process.

Pick your API client tool

Decide which tool you’ll use to make requests:

  • HTTPie. Use this command-line tool to issue individual calls from a prompt.
  • Postman. Go with this if you want the assistance of a graphical user interface to issue calls to the API.

Once you decide, continue with the instructions for your chosen tool: HTTPie or Postman.

Apply the authentication in HTTPie

To use its CLI to issue API calls, apply the credential for HTTPie via python.

Python version

Make sure you have at least version 3.6 installed. You can download the latest version from python.org.

Use pip to install

To simplify the install process, we use pip. It works on Linux, macOS, and Windows, and always provides the latest version of HTTPie. Since we’re using Python v3.6 or greater, pip is already installed. Use this command to verify:

  • Linux/macOS

    $ python -m pip --version
    pip X.Y.Z from .../site-packages/pip (python X.Y)
    
  • Windows

    C:\> py -m pip --version
    pip X.Y.Z from ...\site-packages\pip (python X.Y)
    

Install HTTPie

Once you’ve verified that pip is installed, run this command to install HTTPie and upgrade it to the most recent version:

  • Linux/macOS

    $ python -m pip install --upgrade httpie
    
  • Windows

    C:\> py -m pip install --upgrade httpie
    

Install httpie-edgegrid

You also need the httpie-edgegrid plugin for use in authentication. It’s already available via pip, so you can quickly install it.

  1. From a terminal window or command prompt, navigate to a directory where you want to install the plugin. It doesn’t have to be installed in the same destination as HTTPie.

  2. Run this command to install:

    pip install httpie-edgegrid
    
  3. You can verify installation and check the version by running this command:

    pip show httpie-edgegrid
    

Set up your .edgerc file

The httpie-edgegrid plugin relies on a credentials file that Control Center creates when you set up authentication for an API client.

  1. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  2. Click Download in the Credentials section.

  3. Open the downloaded file with a text editor and add the value [default] as a header above all text. Your finished file should look like this:

  4. Save the file in your home directory using .edgerc as the filename. Here are some examples of the default home directory location for various operating systems:
    • Linux and macOS. /Users/{login}/.edgerc
    • Windows. C:\Users\{username}\.edgerc

You’re ready to go! See Make API calls with HTTPie for call-formatting specifics and usage examples.

Apply the authentication in Postman

Postman has Akamai EdgeGrid authentication built in. You can easily add your credential to authenticate and start using Akamai’s APIs.

Download and install the Postman app

Postman offers apps for Linux, macOS, and Windows. You can get the app from Postman’s website. See Postman’s learning center article for installation details on each operating system.

Apply your credential authentication values

You need authentication values from the credential you created when you set up authentication for an API client. You apply these values in Postman for access.

  1. Launch Postman.

  2. Select Collections from the toolbar and make sure New Collection is selected.

  3. Click the pencil icon to the right of New Collection to set a new name. We’re using Get started with Akamai APIs. You can use whatever you like.

  4. Click Authorization.

  5. From the Type menu, select Akamai EdgeGrid.

  6. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  7. In the Credentials section, copy the client_secret value.

  8. Return to Postman and paste it in the Client Secret field.

  9. Repeat steps 5–7 for both the access_token and client_token values.

    Tip: Don’t close the API client for you page in Control Center. You use it to set up variables in the next process.

  10. Click Save.

Set up variables

You can use Postman’s Variables feature to assign a reusable value to a variable and call on it whenever you need it. This can help protect sensitive data like your authorization values, or you can use one to quickly call a fixed value in an API request. Here we cover some optional but recommended variables you can create.

First, let’s store the base URL used for all Akamai APIs as a variable. This way, you can quickly call on it when making a request, rather than typing it manually each time.

  1. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  2. In the Credentials section, copy the Host value.

  3. Back in Postman, make sure your Collection is active and click the Variables tab.

  4. In a new row, click Add a new variable and type base_url as its name.

  5. Click its INITIAL VALUE column cell, type https://, and Paste. The CURRENT VALUE column defaults to this same value. Leave it as is.

  6. Click Save.

More on how to use this variable later. Next, let’s hide your Access Token, Client Token, and Client Secret values using variables.

  1. With your Collection selected, click the Authorization tab.

  2. Copy the value you set as your Access Token.

  3. Select the Variables tab. Click Add a new variable in the table. Type access_token as the name.

  4. Click in the INITIAL Value column and Paste.

  5. Select the Authorization tab and repeat steps 2–4 for the Client Token and Client Secret values, naming the variables client_token and client_secret, respectively.

  6. Return to the Authorization tab and delete all content in the Access Token field.

  7. Type {{access in the Authorization field and select the access_token variable from the drop-down.

  8. Repeat step 7, typing {{client to find these variables for both the Client Token and Client Secret.

  9. Click Save.

Your token and secret values are now protected from direct view.

You’re ready to go! See Make API calls with Postman for call-formatting specifics and some usage examples.

Make API calls with HTTPie

HTTPie follows a generic path to authenticate and make a request to an Akamai API:

$ http --auth-type=edgegrid -a default: :{akamai_api-endpoint}

You probably recognize some values here, but some may be unfamiliar:

  • auth-type=edgegrid. This tells the request to use edgegrid for authentication.

  • -a default. This tells the request to reference the [default] section of your .edgerc file for credentials.

  • {akamai-api-endpoint}. This endpoint corresponds to the specific API operation you want to call. You can find a list and explanation of available endpoints in the relevant API’s documentation.

HTTPie sample usage

Here we’re using HTTPie to make a simple dig IP address lookup request using the Diagnostic Tools API:

  1. Request the locations of servers in the Akamai network that can run the diagnostic tools.

    $ http --auth-type=edgegrid -a default: :/diagnostic-tools/v2/ghost-locations/available
    

    The 200 OK response shows the location results:

    HTTP/1.1 200 OK
    Connection: keep-alive
    Content-Length: 6524
    Content-Type: application/json;charset.UTF-8
    Date: Mon, 25 Jun 2018 18:39:57 GMT
    Server: Apache-Coyote/1.1
    X-Trace-Id: c0545b3136fb13bb6
    
    {
        "locations": [
            {
                "id": "oakbrook-il-unitedstates",
                "value": "Oakbrook, IL, United States"
            },
            {
                "id": "vienna-austria",
                "value": "Vienna, Austria"
            },
            {
                "id": "saintpetersburg-russianfederation",
                "value": "Saintpetersburg, Russian Federation"
            },
            {
                "id": "goteborg-sweden",
                "value": "Goteburg, Sweden"
            },
            {
                "id": "perth-wa-australia",
                "value": "Perth, WA, Australia"
            }
        ]
    }
    
  2. Request IP address information for Perth, WA, Australia, using the specific locationId from the previous call, perth-wa-australia.

    $ http --auth-type edgegrid -a default: :/diagnostic-tools/v2/ghost-locations/perth-wa-australia/dig-info?hostName=developer.akamai.com&queryType=A
    

    The 200 OK response shows location-specific results:

    HTTP/1.1 200 OK
    Connection: keep-alive
    Content-Length: 3073
    Content-Type: application/json;charset.UTF-8
    Date: Mon, 25 Jun 2018 18:49:48 GMT
    Server: Apache-coyote/1.1
    X-RateLimit-Limit: 10
    X-Ratelimit-Remaining: 9
    X-Trace-Id: 68585b31394a1a20b
    
    {
        "digInfo":
            "answerSection": [
                {
                    "domain": "developer.akamai.com.",
                    "preferenceValue": null,
                    "recordClass": "IN",
                    "recordType": "CNAME",
                    "ttl": 300,
                    "value": "san-developer.akamai.com.edgekey.net."
                },
                {
                    "domain": "san-developer.akamai.com.edgekey.net.",
                    "preferenceValue": null,
                    "recordClass": "IN",
                    "recordType": "CNAME",
                    "ttl": 300,
                    "value": "e24856.dscx.akanmiedgeonet."
                }
            ]
        }
    }
    

Make API calls with Postman

Use Postman to make requests to an Akamai API straight from its interface. It offers several extra features that make it a little easier to manage complex calls too.

Postman sample usage

Here we’re using Postman to query the Diagnostic Tools API. We’re looking to view all of the IP addresses assigned to a specific Global Traffic Management (GTM) property.

Note: This example assumes you’ve set up variables in Postman.

  1. Launch Postman.

  2. Select Collections{collection-name} and click New Request.

  3. Ensure the method is set to GET and type {{base in the Enter request URL field.

  4. Select the base_url variable from the drop-down menu. This inserts the base URL variable.

  5. Add the list GTM properties endpoint to show all GTM properties. The full value should look like this:

    {{base_url}}/diagnostic-tools/v2/gtm/gtm-properties
    
  6. Click Send. The interface shows a response similar to this:

    {
        "gtmProperties": [
            {
                "property": "origin",
                "domain": "akadns.net",
                "hostName": "origin.akadns.net"
            },
            {
                "property": "origin-r3h",
                "domain": "akadns.net",
                "hostName": "origin-r3h.akadns.net"
            }
        ]
    }
    
  7. Find the applicable hostName for your GTM property and store its property and domain values.

  8. Replace the endpoint path with the list IP addresses for a GTM property operation operation. Keep the {{base_url}} variable value in this field.

  9. Replace the {property} and {domain} variable values with the ones you noted.

  10. Click Send. The response looks like this:

    {
        "gtmPropertyIps": {
            "property": "origin",
            "domain": "akadns.net",
            "testIps": [
                "1.23.45.678",
                "191.011.121.314",
                "15.16.171.81",
                "192.02.122.23",
                "24.25.262.72"
            ],
            "targetIps": [
                "182.93.03.132",
                "133.34.35.363",
                "273.83.94.04"
            ]
        }
    }
    

Now you can review all of the test and target IP addresses that have been assigned to your selected GTM property.

Tip: Click Save at the top right to reuse this operation in Postman. You won’t have to run the original operation to get the property and ‘domain’ values again.

Additional resources

Here are some resources you can use to extend your skills and apply them to improve your experience with Akamai’s APIs: