Introduction

The Network Lists API allows you to create and manage lists you can deploy to the Akamai Network to be used by multiple Akamai products and features. The Network Lists API currently supports two types of lists: IP addresses and geographic-based data.

This API allows you to create and upload a new Network List with a named reference handle. Operations are agnostic with regard to the list’s nature, as this association is made when the list is subscribed to by your Akamai product using Akamai Luna Control Center. For example, you might create and deploy an IP address-based Network List for the purpose of blocking certain IP addresses with your Kona Web Application Firewall (WAF) product. The list is not applied, however, until you subscribe to it with a WAF Firewall Policy.

You can share a Network List across multiple properties, Akamai products, and policies. This API also provides for list manipulation, allowing operations on individual list entries, appending of sets of list entries, or operations on an entire list, where bulk deletion can be effected.

List operations that apply to an entire list require the list to be uploaded in its entirety, resulting in either a success if no synchronization conflicts occur, or an error—retry paradigm, with the caller being provided a fresh list. Rate-limiting considerations govern operations on individual list entries, while size and deletion requirements govern usage of list append operations.

Network List activations result in implementations of updates to all services subscribed to the Network List.

API consumption may involve multiple asynchronous client updates to a single named Network List. Concurrent interaction with the API by multiple API clients is cause for concern. In instances where PUTS seek to replace a stale list (one based on an old sync point), the client call will fail with a message to retry with a newly-provided list. (See List Conflict–409 Status.)

Design Considerations

Design considerations that are core to the data model are:

  • Large conceivable list sizes
  • Concurrent lists updates
  • List sync points for resolution of update conflicts
  • Focus on avoiding table-locking issues consequent to manipulation of large lists

In support of these considerations, the current design implements a simple set of RESTful endpoints to PUT and GET entire Network Lists, POST additions to Network Lists, or PUT and DELETE individual list elements. Central to the PUT and GET operations on an entire list is the list sync point, a sequence number incremented after each change, which provide a conflict-resolution mechanism between concurrent updates. Successful PUT calls return a standard HTTP 201/202 and an updated sync point for confirmation. Where the client update attempts to update a stale list, an HTTP 409 error code is returned in addition to a new current sync point.

Activation of Network Lists automatically affects all active services subscribed to the list. Activation of a Network List only manifests in updated block/allow lists in production if services referencing those lists are active in production.

List Conflict Management

Sync points (“sync-point”) provide a list identifier that uniquely identifies a snapshot of a list at any moment in time and enables resolution of concurrency issues. The sync-point is required for PUTS as indicated in the following sections.

Using IP Addresses

The Network Lists API allows you to work with IP address lists. The list elements can include combinations of IP addresses or IP address blocks expressed in CIDR notation. The raw list data preserves all entries (for example, where a block either encompasses a duplicated IP address or overlaps with another block). Attempts to add an IP address that already exists in the list will succeed, but the list will remain unchanged.

Akamai supports a maximum of 50,000 IP addresses or CIDR blocks per list.

Using Country Codes

The Network Lists API also allows you to work with geographic (geo) lists of country codes. Here, you must use the codes associated with the Akamai EdgeScape product, which you can find in Akamai Luna Control Center on the EdgeScape country codes page (SupportUser and Developer GuidesEdgeScapeData CodesCountry Codes).

Other Considerations

Network List elements must be valid IP addresses, CIDR blocks (v4 or v6), or geographic locations. Attempts to add an IP/CIDR block to a geo list or vice versa returns an error (HTTP code 409 - Conflict).

Care should be taken to avoid rate-limiting constraints. An HTTP 429 error is returned when the API caller has been rate-limited.

Errors

For all non–2xx HTTPS returned status codes, the error JSON below is returned as outlined. (See Response Codes below for a list of error codes.) The returned HTTP error corresponds to the “status” elements (enabling the caller to not have to query the headers).

HTTP/1.1 404 Not Found
Content-Type: application/json
Reply Body:
{
    "error": {
        "status" : 404
        "message": "additional non-http specific info where relevant",
        "code": "https://luna.akamaiapis.net/network-list/v1/errors/40023.html"
    }
}

Rate Limiting–429 Status

Network Lists API endpoints are subject to a rate-limiting constraint, which is currently set to 1000 requests per hour. When this limit is reached, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop. This is consistent with all protected Akamai assets exposed via API calls.

List Conflict–409 Status

In situations where, say, two entities both want to update an entire list so as to bulk-add many new items, one update could overwrite the other, resulting in data loss. In the REST model, the two entities interact as follows to prevent this from happening:

  1. GET the full list. Make a note of the sync point returned.
  2. Modify the list locally to add (or remove) items from the list, as desired.
  3. PUT the modified list back to Akamai using the sync point from step 1.

If a second entity modifies the list while the first entity is on step 2, the first will see a 409 reply at step 3 indicating the update might cause data loss. From here, the correct action is to begin again at step 1, fetching the updated list and the new sync point.

Response Codes

Code Description
200 OK
201 Created.
202 OK accepted
204 No changes
400 Bad input parameter. Error message should indicate which one and why.
401 Authentication failure
403 Authorization failure
404 Resource not found
405 Request method not expected (generally should be GET or PUT)
409 Conflict
410 Requested resource is no longer available.
411 Content-length header not specified
413 Request body exceeds maximum allowable size.
423 Requested resource is locked.
429 Too many requests
500 Internal server error unexpected condition
501 Not supported
503 Too many requests; service is temporarily unavailable.
507 Data size is over allowable limit.

Last modified: 3/31/2017