Network Lists API Guide

Overview

The Network Lists API allows managing lists of IP addresses and geographical codes which can be shared across properties in an account, for reference elsewhere in the Instart service (for example, in WAF rules, blocking and throttling, etc.). The lists can be dynamically updated.

There are two types of network lists: IP and GEO.

A network list of type IP looks like the following:

{
   "uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "id": "f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "type": "IP",
   "list": [
       "172.16.15.1",
       "172.16.15.2",
       "172.16.15.3",
       "172.16.15.4",
       "172.16.15.5"
   ],
   "name": "blockedips0727",
   "description": "Blocked IPs added 7/27",
   "deprecated": false,
   "entries_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries",
   "entries_batch_deletion_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries/deletions",
   "creation_timestamp": "2018-07-27T17:31:24Z"
}

IP addresses in list can be any IPv4 or IPv6 address or CIDR range.

A network list of type GEO looks like the following:

{
   "uri": "/config/networklists/40906af0-8362-4aad-99cb-646d5e4a76d8",
   "id": "40906af0-8362-4aad-99cb-646d5e4a76d8",
   "type": "GEO",
   "list": [
       "IR",
       "KP",
       "RU",
       "UA"
   ],
   "name": "geoblacklist",
   "description": "Block requests coming from these countries",
   "deprecated": false,
   "entries_uri": "/config/networklists/40906af0-8362-4aad-99cb-646d5e4a76d8/entries",
   "entries_batch_deletion_uri": "/config/networklists/40906af0-8362-4aad-99cb-646d5e4a76d8/entries/deletions",
   "creation_timestamp": "2018-07-30T18:27:09Z"
}

Geo entries must be ISO 3166-1 standard two-letter country codes.

A single list can contain up to 50,000 entries. A single API call can update 5,000 entries. So, for example, to create a list with more than 5,000 entries you would need to make two or more API calls.

Using the Network Lists API

Examples of API calls in this document use the cURL utility.

Authentication is required. You authenticate using one of the following methods:

  • Send a Authorization header which consists of the word "Basic" followed by a string consisting of your username and password separated by a colon (for example, hsimpson:helloMarge123!) and Base64-encoded. It should look something like:|
    Authorization: Basic aHNpbXBzb246bGVsbG6NYXJnZTEyMyE=
  • Use the Session Management API to create a session, which returns a session ID, which you then send with any other API requests as the value of a cookie named authtoken. Use the following to obtain an authentication token:
curl -v -u '<user name>:<user password>' 'https://api.instartlogic.com/ name>/v1/sessions' -X POST

The API sends the following response codes along with the requested data if present:

HTTP codeDescription
200When a page of network lists is successfully returned
400If the query parameters are not valid
401If the authentication token is not valid
403If the issuer of the request is not authorized to view configuration

To get a list of network lists

The networklists GET method returns a pageable list of network IP/geo lists for the account.

There are some query string parameters that can be used to control the paging of the returned results, listed in the table below.

Parameters

NameDescription
pageOptional index of the first page to return. If omitted, it defaults to 1.
countOptional number of lists to include in each page. If omitted, it defaults to 10.
typeAn optional filter for network list type, either IP or GEO. If omitted, both types will appear in the list.
deprecatedOptional flag. When true, deprecated network lists are included; otherwise they are not listed. If omitted, it defaults to false.

On success, a request returns a page in the list of network lists.

Examples

To view a list of network lists:

curl 'https://api.instartlogic.com/acme/v1/config/networklists' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87'

If successful, this returns a list of the first 10 network lists.

In the following example output, several of the list items are omitted for brevity; this in indicated by an ellipsis (...). Note that since the request did not specify page or count, the defaults of 1 and 10 were used.

{
   "uri": "/config/networklists?count=10&page=1",
   "items": [
       {
           "uri": "/config/networklists/49823985-3e8e-4a9c-bfb6-c27f6bfefe46",
           "id": "49823985-3e8e-4a9c-bfb6-c27f6bfefe46",
           "type": "IP",
           "name": "testcidrrange",
           "deprecated": false,
           "entries_uri": "/config/networklists/49823985-3e8e-4a9c-bfb6-c27f6bfefe46/entries",
           "entries_batch_deletion_uri": "/config/networklists/49823985-3e8e-4a9c-bfb6-c27f6bfefe46/entries/deletions",
           "creation_timestamp": "2018-07-27T20:20:04Z"
       },
       {
           "uri": "/config/networklists/323817c5-fd9f-45b4-a8a1-fee613768fcb",
           "id": "323817c5-fd9f-45b4-a8a1-fee613768fcb",
           "type": "IP",
           "name": "blocklist",
           "description": "",
           "deprecated": false,
           "entries_uri": "/config/networklists/323817c5-fd9f-45b4-a8a1-fee613768fcb/entries",
           "entries_batch_deletion_uri": "/config/networklists/323817c5-fd9f-45b4-a8a1-fee613768fcb/entries/deletions",
           "creation_timestamp": "2018-05-07T17:23:37Z"
       },
       {
           "uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50",
           "id": "f8837f00-d6dc-4f63-83e3-7203c457ad50",
           "type": "IP",
           "name": "blockedips0727",
           "description": "Blocked IPs added 7/27",
           "deprecated": false,
           "entries_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries",
           "entries_batch_deletion_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries/deletions",
           "creation_timestamp": "2018-07-27T17:31:24Z"
       },
       ...   

       {
           "uri": "/config/networklists/bc11e8df-e08f-4592-af73-347e3a60e3db",
           "id": "bc11e8df-e08f-4592-af73-347e3a60e3db",
           "type": "IP",
           "name": "mixedaddresslist",
           "description": "This list has both IPv4 and IPv6 addresses in it",
           "deprecated": false,
           "entries_uri": "/config/networklists/bc11e8df-e08f-4592-af73-347e3a60e3db/entries",
           "entries_batch_deletion_uri": "/config/networklists/bc11e8df-e08f-4592-af73-347e3a60e3db/entries/deletions",
           "creation_timestamp": "2018-07-30T20:50:10Z"
       }
   ],
   "total": 11,
   "has_more": true,
   "page_count": 2,
   "page_index": 1,
   "prev_uri": null,
   "next_uri": "/config/networklists?count=10&page=2"
}

Information about the lists is an element in an items array. After the items array is some summary information about the set of network lists:

  • total is the total number of network lists in this account (in this case, 11)
  • has_more is true if there are more pages of lists to display, and false if this is the last page
  • page_count is the total number of pages of list information there are depending on the count parameter. In this example, the account has 11 lists in all, and the default value of 10 was used for count, so there are two pages required to display all the lists
  • page_index is the current starting page, 1 in this example
  • prev_uri shows the URI to pass to the API for the previous page of information, or null if this is the first page
  • next_uri shows the URI to pass to the API for the next page of information, or null if this is the last page

The items in the items array provide information about each list in the account. For example, here is one item from the array

    {
           "uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50",
           "id": "f8837f00-d6dc-4f63-83e3-7203c457ad50",
           "type": "IP",
           "name": "blockedips0727",
           "description": "Blocked IPs added 7/27",
           "deprecated": false,
           "entries_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries",
           "entries_batch_deletion_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries/deletions",
           "creation_timestamp": "2018-07-27T17:31:24Z"
    },

Each item contains

  • the uri that can be used to query the API for information about this specific network list
  • an id (notice that this is passed to the API in the uri as a way of specifying this particular list)
  • the type of the list (IP or GEO)
  • a name
  • a description
  • a deprecated flag  
  • an entries_uri that allows you to query the API for the individual entries in this specific network list
  • an entries_batch_deletion_uri that allows you to delete all the entries in a that list, while keeping all the list's information (to completely delete the entire list, see "To delete a network list" below
  • the creation_timestamp that records the date and time the list was created and, if the list was modified after being created, a modified_timestamp that records the date and time the list was changed

In this example there were 11 network lists available, so the summary information at the end shows

  • has_more is true,
  • page_count is 2
  • page_index is 1
  • prev_uri is null and next_uri is the URI that you would use to query the API for the next page of results

In this example, you would request the next page of results as follows:

To view subsequent pages of the list:

curl 'https://api.instartlogic.com/acme/v1/config/networklists?count=10&page=2' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87'

The API returns the next page of lists:

{
   "uri": "/config/networklists?count=10&page=2",
   "items": [
       {
           "uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9",
           "id": "38262968-278f-41a3-a0f6-c3cf002fdfb9",
           "type": "IP",
           "name": "mixedaddresslist2",
           "description": "This one also includes some IPv4 CIDR ranges",
           "deprecated": false,
           "entries_uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9/entries",
           "entries_batch_deletion_uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9/entries/deletions",
           "creation_timestamp": "2018-07-30T22:17:42Z"
       }
   ],
   "total": 11,
   "has_more": false,
   "page_count": 2,
   "page_index": 2,
   "prev_uri": "/config/networklists?count=10&page=1",
   "next_uri": null
}

In our example there are 11 total lists, so requesting the second page would give you an items array with only the one remaining list, and the summary information shows

  • has_more is false
  • page_count is still 2
  • page_index is now 2
  • prev_uri is now /config/networklists?count=10&page=1
  • next_uri is now null

In the case where there are more than 20 lists, to get each subsequent page, simply increment the page parameter in the URI's query string. The summary data will update accordingly. When the last page is requested, has_more becomes false and next_uri becomes null.

To get a specific network list

The networklists/<networklistID>GET method returns the data for a specific network list.

The following query string parameter can be used:

Parameters

NameDescription
includelistOptional flag to indicate whether the list of IPs or GEO country codes should be included in the data. If omitted, the default is true.

On success, a request returns all the data for the specified network list.

Examples

To view a specific network list:

curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87' -H 'Content-Type: application/json'

This returns the following:

{
   "uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "id": "f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "type": "IP",
   "list": [
       "172.16.15.1",
       "172.16.15.2",
       "172.16.15.3",
       "172.16.15.4",
       "172.16.15.5"
   ],
   "name": "blockedips0727",
   "description": "Blocked IPs added 7/27",
   "deprecated": false,
   "entries_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries",
   "entries_batch_deletion_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries/deletions",
   "creation_timestamp": "2018-07-27T17:31:24Z"
}

Each item contains

  • the uri that was used to query the API for information about this specific network list
  • the id
  • the type of the list (IP or GEO)
  • A list array that contains the entries in this list
  • a name
  • a description
  • a deprecated flag
  • an entries_uri that allows you to query the API for the individual entries in this specific network list
  • an entries_batch_deletion_uri that allows you to delete all the entries in this list, while keeping all the list's information (to completely delete the entire list, see "To delete a network list" below
  • the creation_timestamp that records the date and time the list was created and, if the list was modified after being created, a modified_timestamp that records the date and time the list was changed

If you want to get just the information about the list and not the list entries themselves, you can use includelist=false in the URI query string:

curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50?includelist=false' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87' -H 'Content-Type: application/json'

This returns the same data but without the list element:

{
   "uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "id": "f8837f00-d6dc-4f63-83e3-7203c457ad50",
   "type": "IP",
   "name": "blockedips0727",
   "description": "Blocked IPs added 7/27",
   "deprecated": false,
   "entries_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries",
   "entries_batch_deletion_uri": "/config/networklists/f8837f00-d6dc-4f63-83e3-7203c457ad50/entries/deletions",
   "creation_timestamp": "2018-07-27T17:31:24Z"
}

To get a paged list of entries from a specific network list

Use the networklists/<networklistID>/entries GET method to get a paged listing of entries in a network list.

There are some query string parameters that can be used to control the paging of the returned results, listed in the table below.

Parameters

NameDescription
pageOptional index of the first page to return. If omitted, it defaults to 1.
countOptional number of lists to include in each page. If omitted, it defaults to 100.

On success, a collection of network list entries is returned.

Example

curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/52e5dae1-8e52-4f5b-a093-3ac051d04d43/entries' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87'

On success, the API returns a response like

{
   "uri": "/config/networklists?count=100&page=1&filter=null",
   "items": [
       {
           "uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9/entries/94fee96b-b19f-4b54-9b31-4d5c5b1ae6aa",
           "id": "94fee96b-b19f-4b54-9b31-4d5c5b1ae6aa",
           "entry": "191.129.44.100",
           "added_by": "hsimpson@acme.com",
           "creation_timestamp": "2018-07-30T22:17:42Z"
       },
       {
           "uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9/entries/58d5193b-f420-49e4-8738-014149661e49",
           "id": "58d5193b-f420-49e4-8738-014149661e49",
           "entry": "191.129.44.101",
           "added_by": ""hsimpson@acme.com",
           "creation_timestamp": "2018-07-30T22:17:42Z"
       },
       …

       {
           "uri": "/config/networklists/38262968-278f-41a3-a0f6-c3cf002fdfb9/entries/e41f6019-d5a3-4fcb-b264-6709e3e5900b",
           "id": "e41f6019-d5a3-4fcb-b264-6709e3e5900b",
           "entry": "e9b7:dddd:acb5:804:0:0:0:b01a",
           "added_by": ""hsimpson@acme.com",
           "creation_timestamp": "2018-07-30T22:17:42Z"
       }
   ],
   "total": 25,
   "has_more": false,
   "page_count": 1,
   "page_index": 1,
   "prev_uri": null,
   "next_uri": null
}

In this example output, several of the list items are omitted for brevity; this in indicated by an ellipsis (...).

To get the data for a specific network list entry

Use the networklists/<networklistID>/entries/<entryId> GET method to get the data for a specific network list entry.

On success, network list entry data is returned.

Example

curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/31246c75-448e-4894-9e85-8a7f3f5be22a/entries/51c8b438-8c23-469c-b37c-8ec47e6c1d02' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87' -H 'Content-Type: application/json'

On success, the API returns a response like

{
 "uri": "/config/networklists/52e5dae1-8e52-4f5b-a093-3ac051d04d43/entries/51c8b438-8c23-469c-b37c-8ec47e6c1d02",
 "id": "51c8b438-8c23-469c-b37c-8ec47e6c1d02",
 "type": "IP",
 "network_list_uri": "/config/networklists/52e5dae1-8e52-4f5b-a093-3ac051d04d43"
}

To add new entries to a network list

Use the networklists/<networklistID>/entries/<entryID> POST method with a JSON payload containing the new entry data. Each new IP or GEO code must be prefaced with value. For example:

{"value" : "12.12.12.12","value" : "12.13.12.12"}

Example

curl  'https://api.instartlogic.com/acme/v1/config/networklists/31246c75-448e-4894-9e85-8a7f3f5be22a/entries' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87' -H 'Content-Type: application/json' -X POST
--data '[{"entry":"1.2.3.2"},{"entry":"1.2.1.2"}]'

To delete entries from a network list

On success, a new task which tracks the deployment of the updated network list is returned.

Use the networklists/<networklistID>/<entryId> DELETE method to remove an entry from a network list.

Example

/usr/bin/curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/31246c75-448e-4894-9e85-8a7f3f5be22a/8569ec8e-0f50-442a-8069-4ebf683a54f2' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87'
-H 'Content-Type: application/json' -X DELETE

To delete a network list

On success, a new task ID which tracks the deployment of the updated network list is returned.

The networklists/<networklistID> DELETE method deletes an existing network list. Note that deleting a network list will completely remove the list and all of its data.

On success, no content is returned.

Example

To delete a network list:

curl -v 'https://api.instartlogic.com/acme/v1/config/networklists/31246c75-448e-4894-9e85-8a7f3f5be22a' -H 'Cookie: authtoken=7e27a03bfddf48ebac9e6a4e061cdc87'
-H 'Content-Type: application/json' -X DELETE