Further Aspects of the Resource Model
Enumerated Types
Some configuration keys can accept one or more of a pre-defined set of values. This is known as an enumerated key type, and the list of possible values (with long description) is provided in the reference guide later in this document.
Uploading Files
Resources that represent real files (such as TrafficScript rules) can also be presented in a raw format, where the data returned is the contents of the file. The MIME type of the request payload should be set to application/octet-stream.
Custom Configuration Sets
You can store and retrieve arbitrary name:value configuration pairs in the Traffic Manager configuration system using the REST API. This configuration is replicated across your cluster, and is only accessible through the REST API, SOAP API, and ZCLI.
To store a custom configuration, create an instance of the “custom” resource and set your name:value data to the ”string_lists” property. For example, to create a resource called "customdata", use the following URI:
https://myhost:9070/api/tm/8.3/config/active/custom/customdata
Set the request body to a JSON structure resembling the following:
{
"properties": {
"basic": {
"string_lists": [{
"name": "customname1",
"value": ["val1", "val2"]
},{
"name": "customname2",
"value": "val3"
}]
}
}
}
Using this system, you can organize your custom configuration into logical groups, initially by an instance of the “custom” resource, and within this, by a name:value pair. Each value can itself be a single item or a list of items.
Errors
If the REST server is unable to handle a HTTP request, it returns a HTTP response with an appropriate HTTP error code. The response body is in JSON and contains a data structure describing the error with a unique identifier (separate to the numeric error code) and a description.
The unique identifier is made up of 2 parts:
{section}.{error_type}
Some errors might provide additional formatted information, specified with an optional "error_info" parameter. For example, the REST API uses this parameter to return per-property errors when a value fails validation. The following structure demonstrates the general form of an error:
{
"error": {
"error_id": "{error identifier}",
"error_text": "{error description}",
"error_info": {error specific data structure, optional}
}
}
A validation error occurs when one or more of the properties within a configuration resource fail a validation check. The error_info section then contains a sub-error for each property that failed validation. These sub-errors are like normal errors in that they contain an identifier (error_id) and a human readable text description (error_text):
{
"error": {
"error_id": "resource.validation_failed",
"error_text": "Some of the properties in the resource failed validation.",
"error_info": {
"basic": {
"key1": {
"error_id": "num.range",
"error_text": "Value must be in range 1000 - 2000."
}
}
}
}
}
Configuration Backups
The REST service supports the ability to create new backup sets of your Traffic Manager configuration.
When a user creates a new backup in the Admin UI, the Traffic Manager copies the current configuration folder ($ZEUSHOME/zxtm/conf) into a new backup directory under $ZEUSHOME/zxtm/confarchive. The name of the backup directory reflects the name chosen in the Admin UI.
Each backup set is saved with a series of metadata files:
|
Filename |
Purpose |
|
DESCRIPTION |
Description of the backup |
|
NAME |
Optional file containing the name of the backup |
|
VERSION_<version> |
File to indicate the software version of the Traffic Manager used to create the backup. This file has no contents. |
|
TIMESTAMP |
File indicating when the backup was created. |
|
PARTIAL |
Indicates that the backup is a partial backup. |
To learn more about configuration backups, see the Pulse Secure Virtual Traffic Manager: User’s Guide.
The REST service exposes only the name and description metadata for your backups, although each listed file is still present in a backup archive on the Traffic Manager.
Backups are represented through the REST API as child resources of the System Information resource:
/api/tm/8.3/status/<tm>/backups/full
As with all System Information resources, you must specify the cluster member you want to interrogate (denoted by <tm> in the URI shown). Each child resource of this URI is named in accordance with the corresponding backup name.
Listing Existing Backups
To see the configuration backups currently stored in a Traffic Manager, perform a GET request for the backups parent resource:
/api/tm/8.3/status/<tm>/backups/full
If successful, the server returns a "200 OK" response code with the backup list in the response body:
{
"children": [{
"name": "Backup 1",
"href": "/api/tm/3.9/status/mytm/backups/full/Backup%201/"
}, {
"name": "vTMBackup-May16",
"href": "/api/tm/3.9/status/mytm/backups/full/vTMBackup-May16/"
}, {
"name": "another backup",
"href": "/api/tm/3.9/status/mytm/backups/full/another%20backup/"
}]
}
To observe the metadata for a specific backup, perform a GET request for a child name. For example, a request for /api/tm/8.3/status/<tm>/backups/full/vTMBackup-May16 might return the following JSON strucure in the response body:
{
"properties": {
"backup": {
"description": "Backup for May 2016",
"time_stamp": 1462445371,
"version": "<version>"
}
}
}
Creating a Backup
To create a new backup, use an HTTP PUT request to the backups URI:
/api/tm/8.3/status/<tm>/backups/full/<backup_name>
Set <backup_name> as the name of the backup you want to create.
The request body must contain a JSON resource representing the backup, with an optional description:
{
"properties": {
"backup": {
"description": "My vTM backup for today",
}
}
}
Set the Content-Type header to “application/json”.
If your backup request is successful, the Traffic Manager returns a “201 Created” response with the full backup metadata in the response body. If the Traffic Manager cannot create the backup, the response contains an HTTP error and the body contains an explanation of why the backup was unsuccessful.
Make sure your backup name does not already exist. The Traffic Manager does not override existing backups and instead returns an error in the response.
Restoring a Backup
Restoring a backup means your current configuration is overwritten permanently and all unsaved changes are lost. Ivanti strongly recommends only performing the following procedure if you are sure of the results.
To restore a backup to be your current Traffic Manager configuration, send a PUT request with the name of the selected backup in the URI, with a “restore” argument:
/api/tm/8.3/status/<tm>/backups/full/MyBackup?restore
Set the request body to an empty properties structure, such as the following:
{
"properties":{
}
}
If your restore request is successful, the Traffic Manager returns a “200 OK” response with the backup metadata in the response body. If the Traffic Manager is unable to restore the backup, the response contains an HTTP error and the body contains an explanation of why the operation was unsuccessful.
Downloading Backups
To download a backup as a TAR archive file, peform a GET request with the name of the required backup appended to the base backups URI. For example:
/api/tm/8.3/status/<tm>/backups/full/MyBackup
Set the “Accept” header to “application/x-tar”.
When the request is made, a TAR file will be generated, which will be streamed to the client.
Some backup clients are able to make the request, but cannot properly handle an application/x-tar response. In this case, Ivanti recommends a command line tool such as CURL. The following command is an example of how to download a backup with CURL:
curl -H "accept:application/x-tar"
-u <username>:<password>
http://<host>:<port>/api/tm/8.3/status/<tm>/backups/full/MyBackup > MyBackup.tar
Uploading Backups
To upload a configuration backup file to your Traffic Manager /confarchive directory, use an HTTP POST request to the base backups URI:
/api/tm/8.3/status/<tm>/backups/full
The name of the backup is not required in the URI; instead, the Traffic Manager uses the contents of the “NAME” file in the backup TAR archive file. Make sure the backup name does not already exist in the Traffic Manager backups list.
Before you send the request, attach your backup archive file and set the Content-Type header to “application/x-tar”. The actual process of uploading or attaching the archive file depends on your REST client.
The REST service returns a "201 Created" response for a correctly uploaded configuration backup archive file. If the Traffic Manager is unable to upload the backup file, the response contains an HTTP error and the body contains an explanation of why the operation was unsuccessful.
Deleting Backups
To delete a configuration backup, perform a DELETE request with the full URI of the backup you want to remove. For example, to remove a backup called “MyBackup”, use the following URI:
/api/tm/8.3/status/<tm>/backups/full/MyBackup
If the request is successful, a "204 No Content" empty-body response is returned.