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.
GET https://mqhost.com:5554/mgmt/actionqueue/
{
"_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}"
}
}
}
GET https://mqhost.com:5554/mgmt/actionqueue/default/operations
{
"_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
GET https://mqhost.com:5554/mgmt/metadata/default/operations/AddPasswordMap
{
"_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.
{
"{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
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."
}
}
{
"_links": {
"self": {
"href": "/mgmt/actionqueue/default"
}
},
"error": [
"Schema validation failure. Please check the operation schema
and default log for more information."
]
}