The Network Lists API

The Network Lists API allows you to manage a common set of lists for use in various Akamai security products such as Kona Site Defender, Web App Protector, and Bot Manager. Network lists are shared sets of IP addresses, CIDR blocks, or broad geographic areas. Along with managing your own lists, you can also access read-only lists that Akamai dynamically updates for you.

This API version 2 provides minor updates to standardize URL endpoint patterns. It consolidates the ability to search for network lists, and to list them as a collection. Viewing these collections is now much faster by default. This API version also removes support for sharing lists across accounts. You should update your tools to migrate away from the superseded Version 1.

Who Should Use This API

Use this API if you want to programmatically manage whitelists of IP addresses and CIDR blocks under your control, integrating them with security configurations within Akamai products. Use it if you want to leverage Akamai-managed lists for use in your own security monitoring applications. Akamai provides dynamic CIDR block whitelists of popular cloud providers, and blacklists that keep track of threatening sources such as dark-web TOR nodes. You can also integrate IP blacklists from other providers into your network monitoring tools. Otherwise as an alternative to identifying IP addresses as they emerge, you can respond to threat patterns more broadly by blocking traffic from entire countries. You can also use this feature to restrict overall access to your web assets to specific countries.

Getting Started

To start using this API:

  • Review Get Started on tools that Akamai provides for all its APIs.

  • Review Authorize Your Client to create your API access credentials and authorizations. As detailed in the API Identity Model section, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • Review the Authorize Your Client section to make sure the identity under which you provision the API can access its full range of functionality. You need access to an Akamai security product such as Kona Site Defender, Web App Protector, or Bot Manager. Make sure that you have read/write access if you want to modify your own set of network lists. Use the Identity Management application to expand access if necessary, or the Identity Management API as a programmatic alternative.

Concurrency Control

To make sure different API clients don’t overwrite each other’s data, this API supports optimistic concurrency control for any modifications to network lists.

Whenever you run the Get a Network List GET operation, your need to retain the value of the response’s syncPoint and pass it back in when you subsequently run the Update a Network List PUT operation. The update operation only succeeds if there haven’t been any interim updates by other API clients. If the update fails, you get a 409 error response.

Note that you only need to pass in the syncPoint value when updating the entire network list object, with or without its complete list of elements. The following operations that only modify the set of elements do not require a syncPoint value:

The response from these operations provide an updated syncPoint value, which you would need for any update to the main network list object, even for a change that doesn’t modify the list of elements.

Partial GET and PUT Options

When reading and writing NetworkList objects, you may wish to modify its top-level members rather than its complete list of elements, or other extraneous metadata. The API offers two query parameters, includeElements and extended to speed up GET requests for this top-level data, and to speed up responses that reflect requested changes. When you set includeElements to false, you don’t get the full list of elements. When you set extended to false, you don’t get data about activation status or the object’s creation and latest modification.

Whenever you run the Update a Network List operation, you have the option to PUT back this smaller object, omitting many data members from your request, such as the list of elements, without affecting corresponding values. See the NetworkList for overall membership requirements.

API Hypermedia

Many of this API’s response objects feature hypermedia links, which allow your API client to navigate directly to related operations on a relevant resource. This additional set of data specifies a contextual href for the resource, along with any non-GET method you need to call it with.

All links objects are arranged as a map, where the object keys serve as descriptive link relations. The following lists these link relations, along with the corresponding API operation they enable.

See the Hypermedia object for more details on the data structure.

The following example shows a set of links for an individual network list:

{
    "name": "Ec2 Akamai Network List",
    "uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
    "syncPoint": 65,
    "type": "IP",
    "networkListType": "networkListResponse",
    "account": "Kona Security Engineering",
    "accessControlGroup": "Top-Level Group: 3-12DAF123",
    "elementCount": 13,
    "readOnly": true,
    "list": [
        "13.125.0.0/16", "13.126.0.0/15", "13.210.0.0/15",
        "13.228.0.0/15", "13.230.0.0/15", "13.232.0.0/14",
        "13.236.0.0/14", "13.250.0.0/15", "13.54.0.0/15",
        "13.56.0.0/16", "13.57.0.0/16", "13.58.0.0/15",
        "174.129.0.0/16"
    ],
    "links": {
        "activateInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/activate",
            "method": "POST"
        },
        "activateInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/activate",
            "method": "POST"
        },
        "appendItems": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/append",
            "method": "POST"
        },
        "retrieve": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU"
        },
        "statusInProduction": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/PRODUCTION/status"
        },
        "statusInStaging": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU/environments/STAGING/status"
        },
        "update": {
            "href": "/network-list/v2/network-lists/1024_AMAZONELASTICCOMPUTECLOU",
            "method": "PUT"
        }
    }
}

Last modified: 4/11/2018