Skip to main content
Skyhigh Security

Working with lists

You can use the REST interface to work with lists and their entries on the appliance where you are currently working.

When working with lists, you include the list parameter in all requests. For list entries, you add the entry parameter.

With lists, you can:

  • Retrieve a list of lists
  • Retrieve a list
  • Add a list with content
  • Add a list with content including type and name
  • Add an empty list
  • Modify a list
  • Rename a list
  • Copy a list
  • Delete a list

With list entries, you can:

  • Retrieve a list of list entries
  • Retrieve a list entry
  • Insert a list entry
  • Modify a list entry
  • Move a list entry
  • Delete a list entry 
Retrieving a list of lists

Request formats
<URL>/list
<URL>/list?page=<int>&pageSize=<int>
<URL>/list?type=<string>
<URL>/list?type=<string>&page=<int>&pageSize=<int>
<URL>/list?name=<string>
<URL>/list?name=<string>&page=<int>&pageSize=<int>
<URL>/list?type=<string>&name=<string>
<URL>/list?type=<string>&name=<string>&page=<int>&pageSize=<int> 

You can retrieve a list of all lists from the appliance where you are currently working.

You can also specify a list type, for example, string, to retrieve a list that includes only lists of this type. Similarly, you can use a list name to retrieve all lists with this name. You can combine these requests.

You can request a particular page of the feed that is returned and specify the page size.

The xml file in the feed provides a list ID for each list. This ID allows you to identify a list that you want to work with.

Sample commands

Retrieve a list of all lists on the appliance where you are currently working:

curl -i -b cookies.txt -X GET "$REST/list"

Retrieve a list of all string lists on the appliance where you are currently working:

curl -i -b cookies.txt -X GET "$REST/list?type=string"

Retrieve a list of all lists named "default" on the appliance where you are currently working:

curl -i -b cookies.txt -X GET "$REST/list?name=default"

 Variable request parameters

Parameter Type Description
type String List type, which can be:
  • category
  • ip
  • iprange
  • mediatype
  • number
  • regex
  • string

Default: None

name String Name of a list, for example, default
Default: None
page Integer Number of a page in a feed with a list of lists
Default: 1
pageSize Integer Size of a page in a feed
Default: –1
Retrieving a list

Request format
<URL>/list/<list ID>

You can retrieve a list from the appliance where you are currently working.

When retrieving this list, you provide its ID.

The response to this request includes the retrieved list in xml format.

Sample command

Retrieve a list:
curl -i -b cookies.txt -X GET "$REST/list/com.scur.type.regex.4537"

 Variable request parameter

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
Adding a list with content

Request format
<URL>/list?type=<string>&name=<string>

You can add a list with content to the lists on the appliance where you are currently working.

When adding this list, you provide its type and name and append it in xml format as the request body. You must also specify a Content-Type header.

After adding the list, you must commit this change using a separate command.

The response to this request includes the added list in xml format as the response body.

Sample command

Add a list with content:

curl -i -b cookies.txt -H "Content-Type: application/xml" -d @categoryListWithContent.xml
-X POST "$REST/list?type=category&name=newlist"

 Variable request parameters

Parameter Type Description
type String List type, which can be:
  • category
  • ip
  • iprange
  • mediatype
  • number
  • regex
  • string

Default: None

name String Name of an added list, for example, newlist
Default: None
 Adding a list with content including type and name

Request format
<URL>/list

You can add a list with content that includes its type and name to the lists on the appliance where you are currently working.

When adding a list in this way, you do not provide a type and name, but simply append the list in xml format as the request body. You must also specify a Content-Type header.

After adding the list, you must commit this change using a separate command.

The response to this request includes the added list in xml format.

Sample command

Add a list with content that includes type and name:

curl -i -b cookies.txt -H "Content-Type: application/xml"
-d @listWithTypeAndNameInside.xml -X POST "$REST/list"

Request parameters
None

Adding an empty list

Request format
<URL>/list?type=<string>&name=<string>

You can add an empty list to the lists on the appliance where you are currently working.

When adding this list, you provide its type and name.

After adding the list, you must commit this change using a separate command.

The response to this request includes the empty list in xml format.

Sample command

Add an empty list:

curl -i -b cookies.txt -X POST "$REST/list?type=ip&name=emptyiplist"

 Variable request parameters

Parameter Type Description
type String List type, which can be:
  • category
  • ip
  • iprange
  • mediatype
  • number
  • regex
  • string

Default: None

name String Name of a list, for example, emptylist
Default: None
Modifying a list

Request format
<URL>/list/<list ID>

You can modify a list on the appliance where you are currently working.

When modifying this list, you provide its ID and append the modified content in xml format as the request body.

You must also specify a Content-Type header.

After modifying the list, you must commit this change using a separate command.

The response to this request includes the modified list in xml format.

Sample command

Modify a list:

curl -i -b cookies.txt -H "Content-Type: application/xml"
-d @modifiedContent.xml -X PUT "$REST/list/com.scur.type.regex.4537"

 Variable request parameter

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
 Renaming a list

Request format
<URL>/list/<list ID>/rename?name=<string>

You can rename a list on the appliance where you are currently working.

When renaming this list, you provide its ID and the new name for the list.

After renaming the list, you must commit this change using a separate command.

The response to this request includes the renamed list in xml format.

Sample command

Rename a list:

curl -i -b cookies.txt -X POST "$REST/list/com.scur.type.regex.4537/rename?name=newname"

 Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
name String Name of a renamed list, for example, newname
Default: None
Copying a list

Request format
<URL>/list/<list ID>/copy?name=<string>

You can copy a list on the appliance where you are currently working.

When copying this list, you provide its ID and a name for the copied list.

After copying the list, you must commit this change using a separate command.

The response to this request includes the copied list in xml format.

Sample command

Copy a list:
curl -i -b cookies.txt -X POST "$REST/list/com.scur.type.regex.4537/copy?name=newname"

 Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
name String Name of a copied list, for example, othername
Default: None
 Deleting a list

Request format
<URL>/list/<list ID>

You can delete a list on the appliance where you are currently working.
When deleting a list, you provide its ID.

Sample command

Delete a list:
curl -i -b cookies.txt -X DELETE "$REST/list/com.scur.type.regex.4537"

Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
Retrieving a list of list entries

Request formats
<URL>/list/<list ID>/entry
<URL>/list/<list ID>/entry?page=<int>&pageSize=<int>

You can retrieve a list of the entries in a list on the appliance where you are currently working.

When retrieving this list, you provide the ID of the list that contains the entries.

You can request a particular page of the feed that is returned and specify the page size.

The feed provides a list of the entries in xml format with a number for each entry to indicate its position. This number allows you to identify an entry that you want to access.

Sample command

Retrieve the entries of a list on the appliance where you are currently working:

curl -i -b cookies.txt -X GET "$REST/list/com.scur.type.regex.4537/entry"

Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
page Integer Number of a page in a feed with list entries
Default: 1
pageSize Integer Size of a page in a feed
Default: –1
Retrieving a list entry

Request format
<URL>/list/<list ID>/entry/<position>

You can retrieve an entry from a list on the appliance where you are currently working.
When retrieving an entry, you provide the list ID and the position of the entry in the list.
The response to this request includes the entry in xml format.

Sample command

Retrieve an entry in a list:

curl -i -b cookies.txt -X GET "$REST/list/com.scur.type.regex.4537/entry/2"

 Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
position  Integer Position of an entry in a list
The position is specified as i –1. For example, for the third entry, specify 2.
Default: None
Inserting a list entry

Request format
<URL>/list/<list ID>/entry/<position>/insert

You can insert an entry in a list on the appliance where you are currently working.

When inserting an entry, you provide the list ID and the position for the entry in the list.

You must also specify a Content-Type header and append the entry in xml format as the request body.

After inserting the entry, you must commit this change using a separate command.

The response to this request includes the inserted entry in xml format.

Sample command

Insert an entry in a list:

curl -i -b cookies.txt -H "Content-Type: application/xml" -d @newEntry.xml
-X POST "$REST/list/com.scur.type.regex.4537/entry/1/insert"

 Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
position  Integer Position for an entry in a list
The position is specified as i – 1. For example, to insert an entry in third position, specify 2.
Default: None
 Modifying a list entry

Request format
<URL>/list/<list ID>/entry/<position>

You can modify an entry in a list where you are currently working.

When modifying this entry, you provide the list ID and the position of the entry in the list.

You must also specify a Content-Type header and append the modified content in xml format as the request body.

After modifying the entry, you must commit this change using a separate command.

The response to this request includes the modified entry in xml format.

Sample command

Modify an entry in a list:

curl -i -b cookies.txt -H "Content-Type: application/xml" -d @modifiedEntry.xml
-X PUT "$REST/list/com.scur.type.regex.4537/entry/3"

 Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
position  Integer Position of an entry in a list
The position is specified as i – 1. For example, when modifying the third entry, specify 2.
Default: None
 Moving a list entry

Request format
<URL>/list/<list ID>/entry/<position>/move?newpos=<int>

You can move an entry in a list on the appliance where you are currently working.

When moving this entry, you provide the list ID and the old and new positions of the entry in the list.

After moving the entry, you must commit this change using a separate command.

The response to this request includes the entry on its new position in xml format.

Sample command

Move an entry in a list:

curl -i -b cookies.txt -X POST "$REST/list/com.scur.type.regex.4537/entry/4/move?newpos=1"

Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
position  Integer Position of an entry in a list
The position is specified as i – 1. For example, when moving an entry from second
position, specify 1.
Default: None
newpos Integer New position of an entry in a list
The position is specified as i – 1. For example, to move an entry to fourth position,
specify 3.
Default: None
 Deleting a list entry

Request format
<URL>/list/<list ID>/entry/<position>

You can delete an entry from a list on the appliance where you are currently working.

When deleting this entry, you provide the list ID and the position of the entry in the list.

Sample command

Delete an entry in a list:

curl -i -b cookies.txt -X DELETE "$REST/list/com.scur.type.regex.4537/entry/0"

Variable request parameters

Parameter Type Description
list ID String List identifier, for example, com.scur.type.regex.4537
Default: None
position  Integer Position of an entry in a list
The position is specified as i – 1. For example, to delete the third entry, specify 2.
Default: None
Sample script for working with lists

The following bash script modifies an entry in a list on the appliance you are currently working on.

Before performing this operation, the script sets a URL variable for accessing the REST interface.

Some list operations require a commit, for example, modifying a list entry. When a commit is required for an operation, this is mentioned in the description.

 ## Set URL variable for accessing REST interface
REST=http://localhost:4711/Konfigurator/REST
## Log on and authenticate
curl -i -c cookies.txt -X POST "$REST/login?userName=myUserName&pass=myPassword"
## Modify list entry
curl -i -b cookies.txt -H "Content-Type: application/xml" -d @modifiedEntry.xml
-X PUT "$REST/list/com.scur.type.regex.4537/entry/3"
## Commit modification
curl -b cookies.txt -X POST "$REST/commit"
## Log off
curl -b cookies.txt -X POST "$REST/logout"
  • Was this article helpful?