Triggering appliance operations by using the REST management interface

A subset of appliance operations can be triggered by using the REST management interface.

When you use the REST management interface for this purpose, you send HTTP requests to the REST interface port and receive JSON-formatted responses with a payload and indication of success or failure. You can incorporate requests into programs and so automate interaction with the appliance.

Before you trigger an operation on the appliance, you must become familiar with the actionqueue resource of the REST management interface. This resource exposes the appliance operation capabilities. You can find the available options for the actionqueue resource by sending a request like the one in the following example:
GET https://mqhost.com:5554/mgmt/actionqueue/
This request returns the following response, describing how to form an actionqueue request:
{
  "_links": {
    "self": {
      "href": "/mgmt/actionqueue/"
    },
    "resource": {
      "href": "/mgmt/actionqueue/{domain}"
    },
    "operations": {
      "href": "/mgmt/actionqueue/{domain}/operations"
    },
    "schema": {
      "href": "/mgmt/actionqueue/{domain}/operations/{operation}"
    },
    "metadata": {
      "href": "/mgmt/metadata/{domain}/operations/{operation}"
    }
  }
}
To see the actual operations that are available for you to request, enter a request based on the following example:
GET https://mqhost.com:5554/mgmt/actionqueue/default/operations
The response that is returned from the actionqueue operations URI shows all supported operations on the appliance in the current firmware release. The following example shows a partial response payload to this request.
{
  "_links": {
    "self": {
      "href": "/mgmt/actionqueue/default/operations"
    },
    "AddPasswordMap": {
      "schema": {
        "href": "/mgmt/actionqueue/{domain}/operations/AddPasswordMap"
      },
      "metadata": {
        "href": "/mgmt/metadata/{domain}/operations/AddPasswordMap"
      }
    },
    "AddTrustedHost": {
      "schema": {
        "href": "/mgmt/actionqueue/{domain}/operations/AddTrustedHost"
      },
      "metadata": {
        "href": "/mgmt/metadata/{domain}/operations/AddTrustedHost"
      }
    },"ApplyPatch": {
      "schema": {
        "href": "/mgmt/actionqueue/{domain}/operations/ApplyPatch"
      },
      "metadata": {
        "href": "/mgmt/metadata/{domain}/operations/ApplyPatch"
      }
    },
    ...
}

Search the response payload for the operation you want. If the operation does not appear in the returned list, the REST management interface does not currently support it. Instead, you must use one of the other interfaces to trigger that operation (for example, the CLI or the Web UI). If the operation is in the returned list, it is supported and can be triggered by using the REST management interface. You can use the schema and metadata embedded links to retrieve additional information about the required parameters for an operation. This is helpful when you compose the operation request payload, which is explained in the following section.

Compose a valid request payload

To trigger a supported operation by using the REST management interface, construct a valid request payload. You can use the metadata resource of the REST management interface to help you construct a valid payload. For example, to retrieve the metadata for the AddPasswordMap operation, you enter a request based on the following example:
GET https://mqhost.com:5554/mgmt/metadata/default/operations/AddPasswordMap
You receive the following response:
{
  "_links": {
    "self": {
      "href": "/mgmt/metadata/test-domain/operations/AddPasswordMap"
    },
    "doc": {
      "href": "/mgmt/docs/metadata/operations/AddPasswordMap"
    }
  },
  "action": {
    "name": "AddPasswordMap",
    "uri": "crypto/add-password-map",
    "cmd-group": "crypto",
    "cli-alias": "add password-map",
    "parameters": {
      "parameter": [
        {
          "name": "AliasName",
          "required": "true",
          "type": "dmString"
        },
        {
          "name": "Password",
          "required": "true",
          "type": "dmString"
        }
      ]
    },
    "display": "Add Password Map",
    "summary": "Add new password to password map",
    "description-encoded": "QWRkcyBhIHBhc3N3b3JkIHRvIHRoZSBleGlzdGluZyBwYXN
                            zd29yZCBtYXAuIFRoZSBwYXNzd29yZCBhbGlhcyBjYW4gYm
                            UgdXNlZCBpbiB0aGUgY29uZmlndXJhdGlvbiB0byByZWZlc
                            iB0byB0aGUgcGFzc3dvcmQu"
  }
}

You can also acquire the metadata for the operation by looking up the appliance Service-Oriented Management Interface (SOMA) schema for the configuration object. The SOMA schemas are located in the store:///xml-mgmt.xsd file.

From the resource metadata you can identify the properties that are required by the operation. You can also identify the property names to use in the payload. By using this information, you can create a proper JSON request payload. A JSON payload has the following structure:
{
  "{operation_name}": {
    "{parameter1_name}": "{parameter1_value}",
    "{parameter2_name}": "{parameter2_value}",
    "{parameter3_name}": "{parameter3_value}",
    "{parameter4_name}": "{parameter4_value}"
    ...
  }
}
To produce a valid JSON request payload for the REST management interface, substitute {operation_name} and include all required parameters and their values. The following example shows a valid payload to trigger the AddPasswordMap operation.
{
  "AddPasswordMap": {
    "AliasName": "user",
    "Password": "passw0rd"
  }
}

Send a request and interpret the response

After the operation request payload is constructed, you can trigger the operation by using a POST request to the actionqueue resource. The following POST request shows how to trigger the AddPasswordMap operation, it is accompanied by the request payload:
POST https://mqhost.com:5554/mgmt/actionqueue/default
If the operation completed successfully, you see a confirmation response similar to the one in the following example:
{
  "AddPasswordMap": {
    "_links": {
      "self": {
        "href": "/mgmt/actionqueue/default"
      },
      "doc": {
        "href": "/mgmt/docs/actionqueue/operations/AddPasswordMap"
      }
    },
    "AddPasswordMap": "Operation completed."
  }
}
If the operation fails, an error is returned. To determine the cause of failure, examine the error message in the response payload and the appliance default log. One possible cause of failure is schema validation, as shown in the following example. This failure is caused by sending an improperly structured payload to trigger the operation.
{
  "_links": {
    "self": {
      "href": "/mgmt/actionqueue/default"
    }
  },
  "error": [
    "Schema validation failure. Please check the operation schema
     and default log for more information."
  ]
}