
- Overview
- Resources
- API summary
- List network lists
- Create a new network list
- Get a network list
- Update a network list
- Delete a network list
- Append elements to a network list
- Add an element
- Remove an element
- Activate a network list
- Get activation status
- Get a snapshot of an activation
- Update network list details
- Get activation details
- Subscribe to network lists
- Unsubscribe to network lists
- Data
- Errors
Network Lists API v2
Manage common sets of lists used by various Akamai security products and features.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
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 support for fast activation, where deploying updated network lists typically takes less than 10 minutes. Version 2 also 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.
Who should use this API
Use this API if you want to programmatically manage allowlists 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 allowlists of popular cloud providers, and blocklists that keep track of threatening sources such as dark-web TOR nodes. You can also integrate IP blocklists 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.
Get started
To configure this API for the first time:
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named Network Lists, and set the access level to READ-WRITE.
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.
activateInProduction
: Activate a network list in thePRODUCTION
environment.activateInStaging
: Activate a network list in theSTAGING
environment.activationDetails
: Get activation details.appendItems
: Append elements to a network list.create
: Create a new network list, a link that you can access only when listing network lists.retrieve
: Get a network list.statusInProduction
: Get activation status for thePRODUCTION
environment.statusInStaging
: Get activation status for theSTAGING
environment.
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"
}
}
}
Migrate from v1 to v2
The following section describes the functional and structural changes you need to migrate your workflow from v1 to v2 of the API.
The following changes affect all endpoints:
The root path for operations on lists changed from
v1/network_lists
tov2/network-lists
.The format of the API’s common error response object now conforms to the HTTP Problem Details specification that’s standard for Akamai APIs. See the Errors section for more details.
For all operations that modify network lists, such as by adding or removing list items, the API returns the complete modified network list in the response.
The
unique-id
,sync-point
,request-id
, andactivation-status
response members are now nameduniqueId
,syncPoint
,requestId
, andactivationStatus
to align with other Akamai APIs.acgs
have been replaced with contracts and groups.acg
in responses is renamed toaccessControlGroup
.APIs now respond with structured hypermedia objects, whose
href
values allow your API client to navigate to related API operations, optionally using a specifiedmethod
other than GET.
Changes that affect the List network lists operation:
List elements are no longer included in the response by default. To match the original v1 behavior, which includes all elements, set the
includeElements
query parameter totrue
.The new API version removes the separate
/search
endpoint. To search across lists, add asearch
query parameter to the/network-lists
GET operation that specifies the search string. For example:v1/network_lists/search?expression=1.1.1.1
becomes…
v2/network-lists?search=1.1.1.1
This version removes the
extended
query parameter, which controlled whether to include metadata about updates and initial creation in responses. This metadata always appears in v2 responses.
Changes that affect the Create a new network list operation:
- You can now specify a
contractId
andgroupId
when creating Network Lists.
Changes that affect the Update a network list operation:
The
/element
endpoint is now named/elements
. For example:v1/network_lists/345_BOTLIST/element?element=123.123.123.123
becomes…
v2/network-lists/345_BOTLIST/elements?element=123.123.123.123
The POST operation on a network list resource to append a set of elements now uses a separate
/append
POST endpoint. For example, a POST to:v1/network_lists/345_BOTLIST
now becomes a POST to…
v2/network-lists/345_BOTLIST/append
Changes that affect the Activate a network list and Get activation status operations:
Activations now specify networks as
/environments/{env}
URL path parameters rather than as query parameters. For example:v1/network_lists/345_BOTLIST/status?env=production
becomes…
v2/network-lists/345_BOTLIST/environments/PRODUCTION/status
The
sync-point
query parameter now uses async-points
endpoint path to access history resources. For example:v1/network_lists/345_BOTLIST/history?sync%2dpoint=5
becomes…
v2/network-lists/345_BOTLIST/sync-points/5/history
Resources
This section provides details on the API’s various operations.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
List network lists | GET | /network-list/ |
Create a new network list | POST | /network-list/ |
Get a network list | GET | /network-list/ |
Update a network list | PUT | /network-list/ |
Delete a network list | DELETE | /network-list/ |
Append elements to a network list | POST | /network-list/ |
Add an element | PUT | /network-list/ |
Remove an element | DELETE | /network-list/ |
Activate a network list | POST | /network-list/ |
Get activation status | GET | /network-list/ |
Get an activation’s snapshot | GET | /network-list/ |
Update network list details | PUT | /network-list/ |
Get activation details | GET | /network-list/ |
Subscribe to network lists | POST | /network-list/ |
Unsubscribe to network lists | POST | /network-list/ |
List network lists
List all network lists available for an
authenticated user who belongs to a group, optionally filtered
by listType
or based on a search
string. Results appear
within the networkLists
array, which might be empty if no
network lists are available to the client.
GET /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
extended |
Boolean | true |
When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide. |
includeElements |
Boolean | true |
If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default false value when listing more than one network list omits the network list’s elements and only provides higher-level metadata. |
listType |
Enumeration | IP |
Filters the output to lists of only the given type of network lists if provided, either IP or GEO . This corresponds to the NetworkList object’s type member. |
search |
String | 192.168. |
Only list items that match the specified substring in any network list’s name or list of items. |
Status 200
application/json
Object type: NetworkList
Download schema: lists.json
Response body:
{
"networkLists": [
{
"networkListType": "networkListResponse",
"accessControlGroup": "KSD\nwith ION 3-13H1234",
"name": "General List",
"elementCount": 3011,
"readOnly": false,
"shared": false,
"syncPoint": 22,
"type": "IP",
"uniqueId": "25614_GENERALLIST",
"links": {
"activateInProduction": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/activate",
"method": "POST"
},
"activateInStaging": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/STAGING/activate",
"method": "POST"
},
"appendItems": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST",
"method": "POST"
},
"retrieve": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST"
},
"statusInProduction": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
},
"update": {
"href": "/network-list/v2/network-lists/25614_GENERALLIST",
"method": "PUT"
}
}
},
{
"networkListType": "networkListResponse",
"name": "Ec2 Akamai Network List",
"elementCount": 235,
"readOnly": true,
"shared": true,
"syncPoint": 65,
"type": "IP",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"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"
}
}
},
{
"networkListType": "networkListResponse",
"accessControlGroup": "KSD\nTest - 3-13H5523",
"name": "GeoList_1913New",
"elementCount": 16,
"readOnly": false,
"shared": false,
"syncPoint": 2,
"type": "GEO",
"uniqueId": "26732_GEOLIST1913",
"links": {
"activateInProduction": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/PRODUCTION/activate",
"method": "POST"
},
"activateInStaging": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/STAGING/activate",
"method": "POST"
},
"appendItems": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913/append",
"method": "POST"
},
"retrieve": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913"
},
"statusInProduction": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913/environments/STAGING/status"
},
"update": {
"href": "/network-list/v2/network-lists/26732_GEOLIST1913",
"method": "PUT"
}
}
}
],
"links": {
"create": {
"href": "/network-list/v2/network-lists/",
"method": "POST"
}
}
}
Specify a
search
string query parameter if you want to narrow the results based on thename
or any of thelist
elements.To further narrow results, specify either
IP
orGEO
as alistType
query parameter.Set the
includeElements
query parameter totrue
if you want the response to include the complete networklist
array. Note that enabling when gathering more than one network list may unnecessarily slow the response.Set the
extended
query parameter totrue
if you want details about deployment status and the most recent update.Make a GET request to
/
.network-list/ v2/ network-lists{?includeElements, search, extended, listType}
The response’s networkLists
array features a series of
NetworkList objects.
Create a new network list
Creates a new network list.
POST /network-list/
Content-Type: application/json
Object type: NetworkList
Download schema: create.json
Request body:
{
"name": "My New Open List",
"type": "IP",
"description": "Notes about this network list",
"list": []
}
Status 201
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
Build a NetworkList object, featuring at least basic information such as
name
andtype
of list.POST the object to
/
.network-list/ v2/ network-lists
The full NetworkList reflected in the
response features a uniqueId
that you can use whenever accessing it
later with a networkListId
URL parameter.
Get a network list
Gets a network list’s most recent
syncPoint
version.
GET /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Optional query parameters | |||
extended |
Boolean | true |
When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide. |
includeElements |
Boolean | true |
If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default true value includes the list’s contents. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.Set the
extended
query parameter totrue
if you want details about deployment status and the most recent update.Set the
includeElements
query parameter totrue
if you want the response to include the complete networklist
array.Make a GET request to
/
.network-list/ v2/ network-lists/ {networkListId}{?extended, includeElements}
The response features a NetworkList object.
Update a network list
Modify the network list items and properties. Allows you to set the name, description and set of network list items to the resource. The current state of the list will be replaced with the properties and items you provide. The type cannot be changed.
PUT /network-list/
Sample: /network-list/
Content-Type: application/json
Object type: NetworkList
Download schema: update.json
Request body:
{
"name": "My Updated Open List",
"type": "IP",
"description": "Updated notes about this network list",
"syncPoint": 1,
"list": [
"13.230.0.0/15",
"195.7.50.194",
"50.23.59.233"
]
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Optional query parameters | |||
extended |
Boolean | true |
When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide. |
includeElements |
Boolean | true |
If enabled, the response list includes all items. For large network lists, this may slow responses and yield large response objects. The default true value includes the list’s contents. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose the relevant object from thenetworkLists
array whosereadOnly
member isfalse
, and store itsuniqueId
.Run Get a network list to get the network list you want to modify. If you want to modify the full
list
of elements, make sure theincludeElements
query parameter istrue
, as by default. Otherwise you can only modify the network list’s higher-level metadata.Modify the NetworkList object, leaving the
syncPoint
value unchanged. Omitting any other data members from the subsequent request leaves corresponding data unchanged.Set the
includeElements
query parameter totrue
if you want the response to include the complete networklist
array.Set the
extended
query parameter totrue
if you want the response to reflect details about deployment status and the most recent update.PUT the object to
/
.network-list/ v2/ network-lists/ {networkListId}{?extended, includeElements}
The response NetworkList reflects the
modified object with an incremented syncPoint
value. Its size
depends on whether you enabled extended
and includeElements
.
After modifying a network list, run Activate a network list to make it go live.
Delete a network list
Removes a network list. You can only
remove network lists that never activated. To deactivate a
list, you can empty out its list
of elements.
DELETE /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Status 200
application/json
Object type: Message
Download schema: message.json
Response body:
{
"status": 200,
"uniqueId": "33501_TESTLIST",
"syncPoint": 4
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.Make a DELETE request to
/
.network-list/ v2/ network-lists/ {networkListId} The response Message provides basic details on the deleted object.
Append elements to a network list
Appends a set of elements
to a network list. If the networks list’s type
is IP
,
the submitted list
is a series of IP addresses or CIDR
blocks. If the type is GEO
, it’s a set of two-character
country codes.
(See the EdgeScape
Documentation for more information.
For a list of countries, go to Data Codes ⇒
Country Code.)
POST /network-list/
Sample: /network-list/
Content-Type: application/json
Object type: NetworkList
Download schema: append.json
Request body:
{
"list": [
"201.22.44.12",
"8.7.6.0/24"
]
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.Build a minimal NetworkList object, featuring only a
list
array of items you want to append.POST the object to
/
.network-list/ v2/ network-lists/ {networkListId}/ append The response’s NetworkList object reflects the complete modified
list
of elements.
Add an element
Adds the specified element
to the list. If
the network list’s type
is IP
, the value needs to be a
URL-encoded IP address or CIDR block. If the type is GEO
,
it’s a two-character country code.
(See the EdgeScape
Documentation for more information.
For a list of countries, go to Data Codes ⇒
Country Code.)
PUT /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Required query parameters | |||
element |
String | 174.129.0.0/16 |
Specifies the element to add to the network list. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.If the element you want to add is an IP address or CIDR block, the
type
of the object must beIP
. Otherwise if it’s a country code, thetype
needs to beGEO
.Specify the
element
you want to add as a query parameter. Make sure to URL-encode any slash characters included in CIDR block values.Make a PUT request to
/
.network-list/ v2/ network-lists/ {networkListId}/ elements{?element} The response reflects the NetworkList, including the longer
list
of elements.
Remove an element
Removes the specified element
from the
list. If the network list’s type
is IP
, the value is a
URL-encoded IP address or CIDR block. If the type is GEO
,
it’s a two-character country code.
DELETE /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Required query parameters | |||
element |
String | 174.129.0.0/16 |
Specifies the element to remove from the network list. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.If the element you want to remove is an IP address or CIDR block, the
type
of the object needs to beIP
. Otherwise if it’s a country code, it needs to beGEO
.Specify the
element
you want to remove as a query parameter. Make sure to URL-encode any slash characters included in CIDR block values.Make a DELETE request to
/
.network-list/ v2/ network-lists/ {networkListId}/ elements{?element}
The response reflects the NetworkList,
including the shorter list
of elements.
Activate a network list
Activate the most recent
syncPoint
version of a network list in either the
STAGING
or PRODUCTION
environment.
POST /network-list/
Sample: /network-list/
Content-Type: application/json
Object type: ActivationRequest
Download schema: activate.json
Request body:
{
"comments": "Allow IPs of new employees who joined this week",
"notificationRecipients": [
"it-team@example.com",
"security-team@example.com"
]
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
environment |
Enumeration | PRODUCTION |
The environment in which this list’s activation occurs, either STAGING or PRODUCTION . |
Status 200
application/json
Object type: ActivationStatus
Download schema: status.json
Response body:
{
"activationId": 12345,
"activationComments": "Allow IPs of new employees who joined this week",
"activationStatus": "PENDING_ACTIVATION",
"syncPoint": 5,
"uniqueId": "25614_GENERALLIST",
"fast": false,
"dispatchCount": 1,
"links": {
"appendItems": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
"method": "POST"
},
"retrieve": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
},
"statusInProduction": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
},
"syncPointHistory": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
},
"update": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
"method": "PUT"
},
"activationDetails": {
"href": "/network-list/v2/network-lists/activations/12345/"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.Specify an
environment
of eitherSTAGING
orPRODUCTION
.Build an ActivationRequest object, with a set of email
notificationRecipients
and any accompanyingcomments
to clarify the reason for the activation.POST the object to
/
.network-list/ v2/ network-lists/ {networkListId}/ environments/ {environment}/ activate
The ActivationStatus response displays the
activationStatus
, initially as PENDING_ACTIVATION
. From this
point, you can:
Run Get activation status to check when the activation goes fully
ACTIVE
.Retain the
uniqueId
andsyncPoint
values and, at any point, run Get an activation’s snapshot to check the network list’s contents at the time of the activation.
Get activation status
Shows a network list’s activation
status on either the STAGING
or PRODUCTION
environment. The response reflects standard activation
status. For fast activation status, see Get activation
details.
GET /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
environment |
Enumeration | PRODUCTION |
The environment in which this list’s activation occurs, either STAGING or PRODUCTION . |
Status 200
application/json
Object type: ActivationStatus
Download schema: status.json
Response body:
{
"activationId": 12345,
"activationComments": "Allow IPs of new employees who joined this week",
"activationStatus": "PENDING_ACTIVATION",
"syncPoint": 5,
"uniqueId": "25614_GENERALLIST",
"fast": false,
"dispatchCount": 1,
"links": {
"appendItems": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
"method": "POST"
},
"retrieve": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
},
"statusInProduction": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
},
"syncPointHistory": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
},
"update": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
"method": "PUT"
},
"activationDetails": {
"href": "/network-list/v2/network-lists/activations/12345/"
}
}
}
If you don’t already have a
networkListId
, run the List network lists operation, choose an object from thenetworkLists
array, and store itsuniqueId
.Specify an
environment
of eitherSTAGING
orPRODUCTION
.Make a GET request to
/
.network-list/ v2/ network-lists/ {networkListId}/ environments/ {environment}/ status
The ActivationStatus response object features the
network list’s syncPoint
version, along with its activationStatus
.
Get a snapshot of an activation
Gets a version of a network
list in its state when activated, with each version
identified by its syncPoint
value. You can only get
syncPoint
versions that have been activated.
GET /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
syncPoint |
Integer | 65 |
The network list version for which to retrieve the snapshot. This corresponds to the syncPoint the API exchanges for each successive modification to the network list. See Concurrency control for details. |
Optional query parameters | |||
extended |
Boolean | true |
When enabled, provides additional response data identifying who created and updated the list and when, and the network list’s deployment status in both STAGING and PRODUCTION environments. This data takes longer to provide. |
Status 200
application/json
Object type: NetworkList
Download schema: network-list.json
Response body:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
You would typically run this operation based on data available when activating a network list. From the response object, store the activated list’s
syncPoint
version, and store theuniqueId
as anetworkListId
URL parameter.Set the
extended
query parameter totrue
if you want to know if the network list is currently deployed, or details about its creation or most recent update.Make a GET request to
/
.network-list/ v2/ network-lists/ {networkListId}/ sync-points/ {syncPoint}/ history{?extended} The response’s NetworkList object shows the full set of
list
elements at the time of activation.
Update network list details
Update a network list’s name or description.
PUT /network-list/
Sample: /network-list/
Content-Type: application/json
Object type: NetworkList
Download schema: update-details.json
Request body:
{
"name": "My Updated Open List",
"description": "Updated notes about this network list"
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
networkListId |
String | 12345_BLACKLISTEDGEOS |
Unique identifier for each network list. |
Status 204
Get activation details
Provides detailed status for a given activation, including progress on fast activation and other audit information, in addition to information ordinarily available from the Get activation status operation.
GET /network-list/
Sample: /network-list/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
activationId |
Integer | 130439 |
The unique identifier for this activation request. |
Status 200
application/json
Object type: ActivationDetails
Download schema: activation-request.json
Response body:
{
"activationId": 1303191,
"createDate": "2018-03-13T10:26:23.659Z",
"createdBy": "jane.thompson@securedproperty.com",
"environment": "STAGING",
"fast": false,
"networkList": {
"activationComments": "Allow local IPs",
"activationStatus": "PENDING_ACTIVATION",
"links": {
"appendItems": {
"href": "/networklist-api/38069_INTERNALWHITELIST/append",
"method": "POST"
},
"retrieve": {
"href": "/networklist-api/38069_INTERNALWHITELIST"
},
"statusInProduction": {
"href": "/networklist-api/38069_INTERNALWHITELIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/networklist-api/38069_INTERNALWHITELIST/environments/STAGING/status"
},
"syncPointHistory": {
"href": "/networklist-api/38069_INTERNALWHITELIST/sync-points/0/history"
},
"update": {
"href": "/networklist-api/38069_INTERNALWHITELIST",
"method": "PUT"
}
},
"syncPoint": 0,
"uniqueId": "38069_INTERNALWHITELIST"
}
}
When running the Activate a network list operation to activate a network list, store the
activationId
from the response.Make a GET request to
/network-list/
.v2/ activations/ {activationId}
The response is an ActivationDetails object.
Subscribe to network lists
Specifies a set of email addresses to inform portal account recipients about any changes to a set of network lists.
POST /network-list/
Content-Type: application/json
Download schema: subscribe.json
Request body:
{
"recipients": [
"it-team@mycompany.com",
"security-team@mycompany.com"
],
"uniqueIds": [
"32055_REPUTATIONWHITELISTDONO",
"365_AKAMAITOREXITNODES"
]
}
Status 204
Unsubscribe to network lists
Unsubscribes the listed users from a set of network lists.
POST /network-list/
Content-Type: application/json
Download schema: subscribe.json
Request body:
{
"recipients": [
"it-team@mycompany.com",
"security-team@mycompany.com"
],
"uniqueIds": [
"32055_REPUTATIONWHITELISTDONO",
"365_AKAMAITOREXITNODES"
]
}
Status 204
Data
This section provides details for each type of data object the API exchanges.
Download the JSON schemas for this API.
This section’s data schema tables list membership requirements as follows:
✓ | Member is required in requests, or always present in responses, even if its value is empty or null . |
○ | Member is optional, and may be omitted in some cases. |
NetworkList
Encapsulates information about each network list.
Download schema:
network-list.json
Sample GET response:
{
"name": "Ec2 Akamai Network List",
"uniqueId": "1024_AMAZONELASTICCOMPUTECLOU",
"syncPoint": 65,
"type": "IP",
"networkListType": "networkListResponse",
"elementCount": 13,
"readOnly": true,
"shared": 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"
}
}
}
NetworkList members
Member | Type | Required | Description |
---|---|---|---|
NetworkList : Encapsulates information about each network list. |
|||
access |
String | ○ | Name of this network list’s access control group (ACG). |
createDate |
String | ○ | Read-only. ISO 8601 timestamp indicating when the network list was first created. Available only when using the extended query parameter to retrieve network list data. |
createdBy |
String | ○ | Read-only. Username of this list’s creator. Available only when using the extended query parameter to retrieve network list data. |
description |
String | ○ | Detailed description of the list. |
elementCount |
Integer | ○ | Read-only. Reflects the number of elements in the list array, which may not necessarily appear in the object when retrieving the list with the includeElements query parameter set to false . |
expedited |
Enumeration | ○ | Read-only. For clients with access to expedited activations on select servers, provides the most recent activation status in the PRODUCTION environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data. |
expedited |
Enumeration | ○ | Read-only. For clients with access to expedited activations on select servers, provides the most recent activation status in the STAGING environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data. |
links |
Hypermedia | ○ | Encapsulates the set of API hypermedia to access a set of resources related to this network list. The object is arranged as a hash of keys, each of which represents a link relation. |
list |
Array | ○ | Defines the network list’s set of elements. If the type is IP , values are any combination of IPv4 addresses, IPv6 addresses, or CIDR blocks. If the type is GEO , values are ISO 3166 two-character country codes. This array does not appear in the object if you get it with the includeElements query parameter set to false . |
name |
String | ✓ | Display name of the network list. |
networkListType |
Enumeration | ○ | If set to extendedNetworkListResponse , indicates that the current data features members enabled with the extended query parameter. Otherwise a plain networkListResponse value indicates this additional data is absent. |
production |
Enumeration | ○ | Read-only. The most recent activation status of the current list in the PRODUCTION environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data. |
readOnly |
Boolean | ○ | Read-only. If true , indicates that you do not have permission to modify the network list. This may indicate either a network list that Akamai manages, or insufficient permission for your API client’s identity to modify a customer-managed list. The default value is false . |
shared |
Boolean | ○ | Read-only. If true , indicates that this list has been shared with you by Akamai or some other account. The default value is false . Shared lists are always read-only. |
staging |
Enumeration | ○ | Read-only. The most recent activation status of the current list in the STAGING environment. See Activation States for details on each activation state. Available only when using the extended query parameter to retrieve network list data. |
syncPoint |
Integer | ✓ | Identifies each version of the network list, which increments each time it’s modified. You need to include this value in any requests to modify the list. See Concurrency control for details. |
type |
Enumeration | ✓ | The network list type, either IP for IP addresses and CIDR blocks, or GEO for two-letter country codes. |
uniqueId |
String | ✓ | A unique identifier for each network list, corresponding to the networkListId URL parameter. |
updateDate |
String | ○ | Read-only. ISO 8601 timestamp indicating when the network list was last modified. Available only when using the extended query parameter to retrieve network list data. |
updatedBy |
String | ○ | Read-only. Username of this list’s creator. Available only when using the extended query parameter to retrieve network list data. |
ActivationRequest
Requests a new activation.
Download schema:
activate.json
Sample POST request:
{
"comments": "Allow IPs of new employees who joined this week",
"notificationRecipients": [
"it-team@example.com",
"security-team@example.com"
]
}
ActivationRequest members
Member | Type | Required | Description |
---|---|---|---|
ActivationRequest : Requests a new activation. |
|||
comments |
String | ○ | Descriptive text to accompany the activation. This is reflected in the ActivationStatus object’s activationComments member. |
notification |
Array | ○ | List of email addresses of Portal users who receive an email when this activation of this list is complete. Do not add addresses to this list without the recipients’ consent. |
siebelTicketId |
String | ○ | If the activation is linked to a Siebel ticket, this identifies the ticket. |
ActivationStatus
Represents a network list’s activation status, as the response to the Get activation status operation. (This object may also appear within an outer ActivationDetails envelope.)
Download schema:
status.json
Sample GET response:
{
"activationId": 12345,
"activationComments": "Allow IPs of new employees who joined this week",
"activationStatus": "PENDING_ACTIVATION",
"syncPoint": 5,
"uniqueId": "25614_GENERALLIST",
"fast": false,
"dispatchCount": 1,
"links": {
"appendItems": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/append",
"method": "POST"
},
"retrieve": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST"
},
"statusInProduction": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/environments/STAGING/status"
},
"syncPointHistory": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST/sync-points/5/history"
},
"update": {
"href": "/networklist-api/rest/v2/network-lists/25614_GENERALLIST",
"method": "PUT"
},
"activationDetails": {
"href": "/network-list/v2/network-lists/activations/12345/"
}
}
}
ActivationStatus members
Member | Type | Required | Description |
---|---|---|---|
ActivationStatus : Represents a network list’s activation status, as the response to the Get activation status operation. (This object may also appear within an outer ActivationDetails envelope.) |
|||
activation |
String | ○ | Further information related to the activation. This reflects the comments from the initial ActivationRequest. |
activationId |
Integer | ○ | Unique identifier for the most recent activation request. May be absent if the list is inactive, or if this object in embedded within an outer ActivationDetails envelope. |
activationStatus |
Enumeration | ✓ | This network list’s current activation status in the specified environment . See Activation States for details on each activation state. |
dispatchCount |
Integer | ○ | Number of times we have attempted to deploy this security configuration on the network. |
fast |
Boolean | ○ | True when fast metadata activation is in effect. False when this is the first deployment of a network list to an environment using fast metadata activation. |
links |
Hypermedia | ○ | Encapsulates the set of API hypermedia to access a set of resources related to this activation. The object is arranged as a hash of keys, each of which represents a link relation. |
syncPoint |
Integer | ✓ | The version of the currently activated network list. See Concurrency control for details. |
uniqueId |
String | ✓ | Read-only. Unique identifier for this network list, corresponding to the networkListId URL parameter. |
ActivationDetails
Provides additional details about an activation, as the response to the Get activation details operation.
Download schema:
activation-request.json
Sample GET response:
{
"activationId": 1303191,
"createDate": "2018-03-13T10:26:23.659Z",
"createdBy": "jane.thompson@securedproperty.com",
"environment": "STAGING",
"fast": false,
"networkList": {
"activationComments": "Allow local IPs",
"activationStatus": "PENDING_ACTIVATION",
"links": {
"appendItems": {
"href": "/networklist-api/38069_INTERNALWHITELIST/append",
"method": "POST"
},
"retrieve": {
"href": "/networklist-api/38069_INTERNALWHITELIST"
},
"statusInProduction": {
"href": "/networklist-api/38069_INTERNALWHITELIST/environments/PRODUCTION/status"
},
"statusInStaging": {
"href": "/networklist-api/38069_INTERNALWHITELIST/environments/STAGING/status"
},
"syncPointHistory": {
"href": "/networklist-api/38069_INTERNALWHITELIST/sync-points/0/history"
},
"update": {
"href": "/networklist-api/38069_INTERNALWHITELIST",
"method": "PUT"
}
},
"syncPoint": 0,
"uniqueId": "38069_INTERNALWHITELIST"
}
}
ActivationDetails members
Member | Type | Required | Description |
---|---|---|---|
ActivationDetails : Provides additional details about an activation, as the response to the Get activation details operation. |
|||
activationId |
Integer | ✓ | Unique identifier for the activation. |
createDate |
String | ✓ | ISO 8601 timestamp indicating when the network list was first created. |
createdBy |
String | ✓ | Username of this list’s creator. |
environment |
Enumeration | ✓ | The Akamai network on which this activation was requested, either STAGING or PRODUCTION . |
estimate |
String | ○ | Estimated time remaining to complete the activation, in ISO 8601 duration format, relative to when this response generated. This member may be omitted under standard activation when fast indicates false , or during the early processing stages of some fast activations when the activation path is still being determined. |
initial |
Boolean | ○ | Returns true for customers using fast metadata if this is the first deployment this network list in this environment. The initial deployment of a list typically takes about 25 minutes, whereas updates to a already deployed list are much quicker, typically 5 - 10 minutes. |
networkList |
Activation |
✓ | Provides details on the activated network list ordinarily available from the Get activation status operation. |
status |
Enumeration | ○ | Reflects lower-level fast activation status. See Activation States for details on possible status values. This member may be omitted under standard activation when fast indicates false , or after activation has completed. |
Message
A common object that responds to DELETE requests.
Download schema:
message.json
Sample DELETE response:
{
"status": 200,
"uniqueId": "33501_TESTLIST",
"syncPoint": 4
}
Message members
Member | Type | Required | Description |
---|---|---|---|
Message : A common object that responds to DELETE requests. |
|||
status |
Integer | ✓ | HTTP status code used for the response. |
syncPoint |
Integer | ○ | In cases where a network list still exists after the operation, this is the syncPoint required to perform update or delete operations on the list. See Concurrency control for details. |
uniqueId |
String | ○ | In cases where a network list still exists after the operation, this is the unique ID required to perform further operations on the network list. |
Link
Specifies each hypermedia link.
Download schema:
link.json
Link members
Member | Type | Required | Description |
---|---|---|---|
Link : Specifies each hypermedia link. |
|||
detail |
String | ○ | Any additional information about the target of the link. |
href |
String | ✓ | URL to access or perform the action on a related resource. May be expressed as an absolute server path, or relative to the current URL call. |
method |
String | ○ | The HTTP method with which to call the href , GET by default. |
Hypermedia
Encapsulates the set of API hypermedia to access a set of related resources. The object is arranged as a hash of keys, each of which represents a link relation.
Download schema:
list-links.json
Hypermedia members
Member | Type | Required | Description |
---|---|---|---|
Hypermedia : Encapsulates the set of API hypermedia to access a set of related resources. The object is arranged as a hash of keys, each of which represents a link relation. |
|||
activate |
Link | ○ | A link to Activate a network list in the PRODUCTION environment. |
activate |
Link | ○ | A link to Activate a network list in the STAGING environment. |
activation |
Link | ○ | A link to Get activation details. |
appendItems |
Link | ○ | A link to Append elements to a network list. |
retrieve |
Link | ○ | A link to Get a network list. |
status |
Link | ○ | A link to Get activation status for the PRODUCTION environment. |
statusInStaging |
Link | ○ | A link to Get activation status for the STAGING environment. |
update |
Link | ○ | A link to Update a network list. |
Activation states
When polling a network list or one of its activations, various
members’ enumerated values indicate its current state in either the
STAGING
or PRODUCTION
environments. The following reflects basic,
high-level status:
Value | Description |
---|---|
INACTIVE |
The network list is not yet activated. |
PENDING_ACTIVATION |
An activation has launched, but the network list has not yet fully activated. |
ACTIVE |
The network list is currently active. |
MODIFIED |
Indicates that a previous syncPoint version of the network list is currently active, and any subsequent modifications may need to be activated. |
PENDING_DEACTIVATION |
An activation for another syncPoint version of the network list has launched, but it has not yet fully rendered this version INACTIVE . |
FAILED |
The network list has failed to activate. |
The following alternate set, which appears as values in the
ActivationDetails object’s status
member, reflects lower-level fast activation states:
Value | Description |
---|---|
RECEIVED |
The activation request has been received, and is being processed. |
LIVE |
The activation is in the process of deploying across the environment. |
DEPLOYED |
The activation is deployed across the environment, and is being checked for stability. |
ACTIVATED |
The activation is successfully deployed across the environment. |
FAILED |
The activation failed. |
ROLLBACK |
A cancellation request is being processed. |
CANCELING |
The activation partly deployed, but is now being cancelled. |
DEACTIVATED |
A requested deactivation successfully completed across the environment. |
STOPPED |
A requested cancellation or deactivation has been completed across the environment. |
Errors
This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.
Error responses
This API’s error responses follow the
HTTP Problem Details standard.
An additional fieldErrors
object features an entry
array listing
specific problems. Each entry lists at least one value
criteria that
may have triggered the failure.
The following shows a sample error response:
{
"detail": "Validation failed",
"instance": "https://problems.luna.akamaiapis.net/network-lists-activation/error-instances/0835dedb-9d01-4178-985b-c93c7f5fcfa8",
"status": 400,
"title": "Invalid Input Error",
"type": "https://problems.luna.akamaiapis.net/network-lists-activation/error-types/INVALID-INPUT-ERROR",
"fieldErrors": {
"entry": [
{
"key": "createWithPost.arg0",
"value": [ "Invalid network list type: null" ]
},
{
"key": "name",
"value": [ "may not be empty" ]
},
{
"key": "type",
"value": [
"Values cannot be null or empty.",
"may not be null"
]
}
]
}
}
HTTP status codes
The following lists the full range of response codes the API may generate:
Code | Description |
---|---|
200 | The operation was successful. |
201 | Resource successfully created. |
400 | Bad Request. |
403 | Access is forbidden. |
404 | Resource not found. |
409 | Conflict with the resource’s current syncPoint state. See Concurrency control for details. |
500 | Internal server error. |