Performing basic REST operations
When working with the REST interface, you can perform several basic operations such as logging on and off, committing changes, and creating a configuration backup.
Use a POST request for these operations and specify each operation by a parameter that you add to the URL of the request.
For example, this is a request to log off from the REST interface on an appliance, using a curl command:
When a sample command or script with commands is shown in this documentation, a command can extend over two or more lines. When working with the REST interface, you must enter any command completely within a single line.
curl -i -b cookies.txt -X POST "$REST/logout"
Parameters for basic REST operations include:
- login — Log on
- logout — Log off
- heartbeat — Keep a session alive
- commit — Commit changes
- discard — Discard changes
- backup — Back up the configuration
- restore — Restore the configuration
- updateEngines — Update the filter engines
Logging on
Request format: URL/login?userName=<user name>&pass=<password>
To log on to the REST interface on an appliance, use the login parameter. Within the request, you also submit your credentials for authentication. If authentication is successful, the response to the logon request provides a session ID.
Sample command: curl -i -X POST "$REST/login?userName=myusername&pass=mypassword"
Request parameters:
| Parameter | Type | Description |
|---|---|---|
| userName | String | User name submitted for authenticating to the REST interface Default: None |
| pass | String | Password submitted for authenticating to the REST interface Default: None |
Logging off
Request format: URL/logout
To log off from the REST interface on an appliance, use the logout parameter. Logging off deletes the session information and discards the changes made in a session that have not been committed.
Sample command: curl -i -X POST "$REST/logout"
Request parameters: None
Keeping a session alive
Request format: URL/heartbeat
Using the heartbeat parameter in a request keeps the current session alive.
Sample command: curl -i -b cookies.txt -X POST "$REST/heartbeat"
Request parameters: None
Committing changes
Request format: URL/commit
To commit changes that have been made to items such as system files, log files, and lists on an appliance, use the commit parameter.
Sample command: curl -i -b cookies.txt -X POST "$REST/commit"
Request parameters: None
Discarding changes
Request format: URL/discard
To discard changes that have been made to items such as system files, log files, and lists on an appliance, use the discard parameter.
Sample command: curl -i -b cookies.txt -X POST "$REST/discard"
Request parameters: None
Backing up the configuration
Request format: URL/backup or URL/backup?password=string or URL/backup?backUpMAS=boolean&password=string
To create a configuration backup for the appliance where you are currently working, use the backup parameter. When backing up or restoring a configuration, no response header is required as part of the output, so the -i option is not included in the command for performing the request.
The configuration backup is stored in the file that is specified as output in the command.
Sample commands:
curl -b cookies.txt -X POST "$REST/backup" -o filename.backup or: curl -b cookies.txt -X POST "$REST/backup?password=yourpassword" -o filename.backup or: curl -b cookies.txt -X POST "$REST/backup?backUpMAS=true&password=yourpassword" -o filename.backup
Request parameters:
| Parameter | Type | Description |
|---|---|---|
| backUpMAS | Boolean | If true, a password is used to encrypt the backup. Default: false |
| password | String | Password used to encrypt the backup. If no password is specified, the backup is not encrypted. Default: None |
Restoring the configuration
Request format: URL/restore?fullrestore=boolean&restoreMAS=boolean&password=string
To restore the configuration of the appliance you are currently working on, use the restore parameter. You must also specify a Content-Type header for the type of the backup file.
Sample command: curl -b cookies.txt --data-binary @filename.backup -X POST "$REST/restore" -H "Content-Type: text/plain;charset=UTF-8"
Request parameters:
| Parameter | Type | Description |
|---|---|---|
| fullrestore | Boolean | If true, a configuration is restored completely. If false, only the policy is restored, omitting the system settings for an appliance. Default: false |
| restoreMAS | Boolean | If true, MAS is also restored if available. Default: false |
| password | String | Password used to decrypt the backup. If no password is specified, the backup is not decrypted. |
Updating the filter engines
Request format: URL/updateEngines
To perform an update of the filter engines on an appliance with data that is provided offline, use the updateEngines parameter. You must also specify a Content-Type header for the type of the update file.
Sample command: curl -b cookies.txt --data-binary @mwg7-linux-mix-small.upd -X POST "$REST/updateEngines"-H "Content-Type: text/plain;charset=UTF-8"
Request parameters: None
Sample script for performing basic REST operations
The following bash script performs several basic operations: logging on and authenticating to the REST interface on an appliance, creating a backup file, and logging off again.
Before these operations are performed, the script sets a URL variable for accessing the REST interface.
#!/bin/bash ## 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" ## Create backup file curl -b cookies.txt -X POST "$REST/backup" -o filename.backup ## Log off again curl -b cookies.txt -X POST "$REST/logout"