Network Lists API

API Summary

Operation Method Endpoint
Network Lists
List Network Lists GET /network-list/v1/network_lists{?listType,extended,includeDeprecated,includeElements}
Create a Network List POST /network-list/v1/network_lists{?listType,extended,includeDeprecated,includeElements}
Modify a Network List PUT /network-list/v1/network_lists/{networkListId}{?extended}
Get a Network List GET /network-list/v1/network_lists/{networkListId}{?extended}
Add to a Network List POST /network-list/v1/network_lists/{networkListId}{?extended}
Add an Element PUT /network-list/v1/network_lists/{networkListId}/element
Remove an Element DELETE /network-list/v1/network_lists/{networkListId}/element{?element}
Activate a Network List POST /network-list/v1/network_lists/{networkListId}/activate{?env}
Get Activation Status GET /network-list/v1/network_lists/{networkListId}/status{?env}
Get Activation Snapshot GET /network-list/v1/network_lists/{networkListId}/history{?sync%2dpoint,extended}
Search Network Lists GET /network-list/v1/network_lists/search{?expression,listType,extended,includeDeprecated}
Share a Network List POST /network-list/v1/network_lists/{networkListId}/share
List Sharing Status GET /network-list/v1/network_lists/{networkListId}/share

List Network Lists

List all configured Network Lists for the authenticated user.

GET /network-list/v1/network_lists{?listType,extended,includeDeprecated,includeElements}

Example: /network-list/v1/network_lists?listType=IP&extended=true&includeDeprecated=true&includeElements=true

Headers:

  • Accept: application/json

Parameter Type Sample Description
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.
includeDeprecated Boolean true When enabled, includes network lists that have been deleted.
includeElements Boolean true When enabled, includes the full list of IP or GEO elements, otherwise when disabled only provides high-level data about the network list.
listType String IP Filters by the network list type, either GEO or IP.

Status 200 application/json

Response:

{
    "network_lists": [
        {
            "name": "test",
            "type": "IP",
            "links": [
                {
                    "rel": "get 123_TEST",
                    "href": "/network-list/v1/network_lists/123_TEST"
                }
            ],
            "unique-id": "123_TEST",
            "list": [
                "1.2.3.4",
                "5.6.7.8"
            ],
            "sync-point": 1,
            "numEntries": 2
        }
    ]
}

Create a Network List

Create a new Network List.

POST /network-list/v1/network_lists{?listType,extended,includeDeprecated,includeElements}

Example: /network-list/v1/network_lists?listType=IP&extended=true&includeDeprecated=true&includeElements=true

Content-Type: application/json

Headers:

  • X-ECWS-ACG: ACG_ID

Request:

{
    "name": "botlist",
    "type": "IP",
    "list": [
        "201.22.44.12",
        "8.7.6.0/24"
    ]
}

Parameter Type Sample Description
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.
includeDeprecated Boolean true When enabled, includes network lists that have been deleted.
includeElements Boolean true When enabled, includes the full list of IP or GEO elements, otherwise when disabled only provides high-level data about the network list.
listType String IP Filters by the network list type, either GEO or IP.

Status 201 application/json

Response:

{
   "status": 201,
   "unique-id": "345_BOTLIST",
   "links": [
       {
          "rel": "get 345_BOTLIST",
          "href": "/network-list/v1/network_lists/345_BOTLIST"
       }
   ],
   "sync-point": 0
}

Modify a Network List

Update a Network List.

PUT /network-list/v1/network_lists/{networkListId}{?extended}

Example: /network-list/v1/network_lists/345_BOTLIST?extended=true

Content-Type: application/json

Request:

{
   "name": "Simple List",
   "type": "IP",
   "unique-id": "345_BOTLIST",
   "list": [
      "192.168.0.1",
      "192.168.0.2",
      "192.168.0.3",
      "198.168.0.4",
      "198.168.0.5",
      "198.168.0.6"
   ],
   "sync-point": 0
}

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.

Status 200 application/json

Response:

{
   "status": 200,
   "unique-id": "345_BOTLIST",
   "links": [
       {
          "rel": "get 345_BOTLIST",
          "href": "/network-list/v1/network_lists/345_BOTLIST"
       }
   ],
   "sync-point": 1
}

Get a Network List

Get a Network List.

GET /network-list/v1/network_lists/{networkListId}{?extended}

Example: /network-list/v1/network_lists/345_BOTLIST?extended=true

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.

Status 200 application/json

Response:

{
   "name": "Simple List",
   "type": "IP",
   "unique-id": "345_BOTLIST",
   "links": [
       {
          "rel": "get 345_BOTLIST",
          "href": "/network-list/v1/network_lists/345_BOTLIST"
       }
   ],
   "list": [
      "192.168.0.1",
      "192.168.0.2",
      "192.168.0.3",
      "198.168.0.4",
      "198.168.0.5",
      "198.168.0.6"
   ],
   "sync-point": 1,
   "numEntries": 6
}

Add to a Network List

Appends a set of IP addresses or geo locations to a list.

POST /network-list/v1/network_lists/{networkListId}{?extended}

Example: /network-list/v1/network_lists/345_BOTLIST?extended=true

Content-Type: application/json

Request:

{
   "list": [
      "192.168.0.7",
      "192.168.0.8",
      "192.168.0.9"
   ]
}

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.

Status 202 application/json

Response:

{
   "message": "Elements successfully appended to the list",
   "status": 202,
   "links": []
}

Add an Element

Adds the specified element to the list.

PUT /network-list/v1/network_lists/{networkListId}/element

Example: /network-list/v1/network_lists/345_BOTLIST/element

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.

Status 201 application/json

Response:

{
   "message": "Element 1.2.3.4 successfully added to list",
   "status": 201,
   "links": []
}

Remove an Element

Deletes the specified element from the list.

DELETE /network-list/v1/network_lists/{networkListId}/element{?element}

Example: /network-list/v1/network_lists/345_BOTLIST/element?element=123.123.123.123

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
element String 123.123.123.123 Identifies the IP or GEO item to delete.

Status 200 application/json

Response:

{
   "message": "Element 1.2.3.4 successfully deleted from list",
   "status": 200,
   "links": []
}

Activate a Network List

Activates the Network List.

POST /network-list/v1/network_lists/{networkListId}/activate{?env}

Example: /network-list/v1/network_lists/345_BOTLIST/activate?env=production

Content-Type: application/json

Request:

{
 "siebel-ticket-id": "ABC",
 "notification-recipients": [ "nomail@akamai.com" ],
 "comments": "Activation"
}

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
env String production Specifies the target network environment, either production or staging.

Status 200 application/json

Response:

{
   "status": 200,
   "unique-id": "345_BOTLIST",
   "links": [],
   "sync-point": 1,
   "activation-status": "PENDING_ACTIVATION"
}

Get Activation Status

Retrieves the list’s activation status.

GET /network-list/v1/network_lists/{networkListId}/status{?env}

Example: /network-list/v1/network_lists/345_BOTLIST/status?env=production

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
env String production Specifies the target network environment, either production or staging.

Status 200 application/json

Response:

{
   "status": 200,
   "unique-id": "345_BOTLIST",
   "links": [],
   "sync-point": 1,
   "activation-status": "PENDING_ACTIVATION",
   "activation-comments": "Activation"
}

Get Activation Snapshot

Retrieves a snapshot of a Network List at the moment of its activation.

GET /network-list/v1/network_lists/{networkListId}/history{?sync%2dpoint,extended}

Example: /network-list/v1/network_lists/345_BOTLIST/history?sync%2dpoint=5&extended=true

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.
Optional
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.
sync%2dpoint Number 5 Indicates how many times the network list has been modified.

Status 200 application/json

Response:

{
   "name": "Simple List",
   "type": "IP",
   "unique-id": "345_BOTLIST",
   "links": [
       {
          "rel": "get 345_BOTLIST",
          "href": "/network-list/v1/network_lists/345_BOTLIST"
       }
   ],
   "list": [
      "192.168.0.1",
      "192.168.0.2",
      "192.168.0.3",
      "198.168.0.4",
      "198.168.0.5",
      "198.168.0.6"
   ],
   "sync-point": 1
}

Search Network Lists

Retrieves a list of all Network Lists having elements containing the search terms. Each Network List’s status is also provided.

GET /network-list/v1/network_lists/search{?expression,listType,extended,includeDeprecated}

Example: /network-list/v1/network_lists/search?expression=1.1.1.1&listType=IP&extended=true&includeDeprecated=true

Headers:

  • Accept: application/json
  • X-ECWS-ACG: ACG_ID

Parameter Type Sample Description
Optional
expression String 1.1.1.1 Matches items included in network lists.
extended Boolean true If enabled, returns more verbose data such as creation date and activation status.
includeDeprecated Boolean true When enabled, includes network lists that have been deleted.
listType String IP Filters by the network list type, either GEO or IP.

Status 200 application/json

Response:

{
   "createEpoch": 1377894266,
   "updateEpoch": 1378409797,
   "stagingActivationStatus": "INACTIVE",
   "productionActivationStatus": "PENDING_ACTIVATION",
   "createdBy": "user",
   "createDate": 1377894266623,
   "updatedBy": "user",
   "updateDate": 1378409797687,
   "name": "Simple List",
   "type": "IP",
   "unique-id": "345_BOTLIST",
   "links": [
       {
          "rel": "get 345_BOTLIST",
          "href": "/network-list/v1/network_lists/345_BOTLIST"
       }
   ],
   "list": [
      "192.168.0.1",
      "192.168.0.2",
      "192.168.0.3",
      "198.168.0.4",
      "198.168.0.5",
      "198.168.0.6"
   ],
   "sync-point": 1
}

Share a Network List

Shares a Network List with the specified accounts.

POST /network-list/v1/network_lists/{networkListId}/share

Example: /network-list/v1/network_lists/345_BOTLIST/share

Content-Type: application/json

Request:

{
    "accounts": [ "ACCOUNT_ID" ],
    "acgs": [ "ACG_ID" ]
}

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.

Status 200 application/json

Response:

{
   "message": "The list shares were created successfully",
   "status": 200,
   "links": []
}

List Sharing Status

Returns a list of account IDs with which the specified Network List is shared, or returns the keyword ALL if the list is shared with all accounts.

GET /network-list/v1/network_lists/{networkListId}/share

Example: /network-list/v1/network_lists/345_BOTLIST/share

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
networkListId String 345_BOTLIST Unique identifier for the network list, corresponding to the unique-id within the data.

Status 200 application/json

Response:

{
   "accounts": [
       {
          "name": "Account name",
          "accountId": "ACCOUNT_ID"
       }
   ],
   "acgs": [
       {
           "name": "ACG name",
           "acgId": "ACG_ID"
       }
   ],
   "permissions": [
      "permissionA",
      "permissionB"
   ]
}


Last modified: 12/12/2016