REST Lists

Manage lists using the REST API. Each list is stored as a string in a single row in the database and can contain up to 256 MB of data. Use lists for for slow or low data changes or static data lookups, rather than for large transactional data uses.

If a list size exceeds 256 MB, data truncates without an error message.

/rest/decided_list

Manage lists.

Syntax

https://<username>:<password>@<host>/rest/decided_list

POST

Create a list

The body of the request is a JSON object with the following fields.

Field	Required/Optional	Field type	Description
content	Required	JavaScript array	A two dimensional array (array containing arrays containing simple values) which make the contents of your list. If the contents is a single array of values, it's wrapped in another array to create a two dimensional array.
name	Required	String	The name of the list. The name must be unique.

Example request

{
    "content": [
        [
            "1.1.1.1"
        ],
        [
            "1.1.1.2"
        ],
        [
            "1.1.1.3"
        ],
        [
            "1.1.1.4"
        ],
        [
            "1.1.1.5"
        ],
        [
            "1.1.1.6"
        ],
        [
            "1.1.1.7"
        ],
        [
            "1.1.1.8"
        ],
        [
            "1.1.1.9"
        ],
        [
            "1.1.1.10"
        ],
        [
            "1.1.1.11"
        ],
        [
            "2.2.2.12"
        ]
    ],
    "name": "My IP address list"
}

Example response
A successful POST returns a success indicator and the ID of the newly created list.

{
    "id": 41,
    "success": true
}

/rest/decided_list/<list name or id>

Update a list. A POST request can either do a complete update or modify rows in place using one of the following JSON examples.

Syntax

https://<username>:<password>@<host>/rest/decided_list/<list name or id>

POST

Update a list

The body of the request is a JSON object with the following fields.

Field	Required/Optional	Field type	Description
append_rows	Optional	JavaScript array	A two dimensional array. The new rows are appended to the existing rows. If there are values within the top level array that aren't arrays, they're transformed into an array to conform to the two dimensional requirement.
content	Optional	JavaScript array	A two dimensional array (array containing arrays containing simple values) which make the contents of your list. Replaces the current contents with the POSTed contents.
delete_rows	Optional	JavaScript array	An array of row indices (0 based). Each row is deleted.
name	Optional	string	The name of the list. The name must be unique.
update_rows	Optional	JavaScript array	A JavaScript object where the keys are the row numbers to be updated and the values are an array that has the new content of the row. If you pass a single value instead of an array, it's transformed into an array to conform to the array requirement.

The following example does a complete replace.

Example request

{
    "content": [
        [
            "1.1.1.1"
        ],
        [
            "1.1.1.2"
        ],
        [
            "1.1.1.3"
        ],
        [
            "1.1.1.4"
        ],
        [
            "1.1.1.5"
        ],
        [
            "1.1.1.6"
        ],
        [
            "1.1.1.7"
        ],
        [
            "1.1.1.8"
        ]
    ],
    "name": "My IP address list"
}

The following example modifies parts of a list without replacing the entire thing. If you provide the content field, ignores other operations. If the individual cells of the table aren't strings, they're cast as strings.

Example request

{
    "append_rows": [
        [
            "2.2.2.13", "x", "y", "z"
        ]
    ],
    "delete_rows": [ 0, 11 ],
    "update_rows": {
        "0": ["1.1.1.x", "foo", "bar"],
        "5": ["1.1.1.y"],
        "11": ["test"]
    }
}

It's not possible to delete all rows from the list, and the delete_rows commands that attempt to do so results in an error. At least one row must be present in the list.

Example response
A successful POST returns a success indicator.

{
 "success" : True 
}

/rest/decided_list/<list name or id>/formatted_content<query parameters>

Return formatted data. You can get the contents of a list in a delimited format.

Syntax

https://<username>:<password>@<host>/rest/decided_list/<list name or id>/formatted_content<query parameters>

GET

Get formatted data.

The Python CSV module can't handle unicode. Use JSON formatting if unicode must be supported.

The body of the request is a JSON object with the following fields.

Parameter	Required/Optional	Parameter type	Description
_output_format	Optional	"csv", "json", or "txt"	Output the contents either in JSON (default), comma delimited format, or text.
_fs	Optional	Single character	Value is used to separate fields in the same row. Comma by default.
_rs	Optional	Single character	Value is used to separate rows. Newline by default.

Example request

HTTP GET /rest/decided_list/<list name or ID>/formatted_content?_output_format=csv&_fs=,&_rs=%0A

Example response
A successful GET returns contents in comma delimited format.

A, B, C
D,,
E,,F