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:
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:
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:
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"