Part 4: Triggering appliance operations

Content

Introduction

In firmware release 7.2.0.0 of IBM DataPower Gateway, certain action execution capabilities are available through the REST management interface. To use the REST management interface for current DataPower processes, you might still need to rely upon other interfaces for some operations. In Part 4 of this series, you learn which operations are supported in the current firmware release and how to trigger an operation.

Identify supported operations

Before you trigger an operation on the DataPower Gateway, you must become familiar with the actionqueue resource of the REST management interface. This resource exposes the DataPower operation capabilities. You can find the actionqueue resource by accessing the root Uniform Resource Identifier (URI) of the REST management interface:

GET https://dphost.com:5554/mgmt/

Listing 1 shows the response that is received from the REST management interface root URI. This listing shows the available resource categories on the DataPower Gateway. The actionqueue resource is identified by the /mgmt/actionqueue/ URI.

Root URI response

 {
   "_links": {
     "self": {
       "href": "/mgmt/"
     },
     "config": {
       "href": "/mgmt/config/"
     },
     "domains": {
       "href": "/mgmt/domains/config/"
     },
     "status": {
       "href": "/mgmt/status/"
     },
     "actionqueue": {
       "href": "/mgmt/actionqueue/"
     },
     "filestore": {
       "href": "/mgmt/filestore/"
     },
     "metadata": {
       "href": "/mgmt/metadata/"
     },
     "types": {
       "href": "/mgmt/types/"
     }
   }
 }

The available options for the DataPower actionqueue resource are displayed when you access the actionqueue root URI, /mgmt/actionqueue/, as shown by this request:

GET https://dphost.com:5554/mgmt/actionqueue/

Listing 2 shows the response that is returned from the actionqueue root URI. The response shows the available options for the actionqueue resource on the DataPower Gateway.

Actionqueue root URI response

 {
   "_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}"
     }
   }
 }

Before you trigger an operation on the DataPower Gateway, verify that the operation is supported in the current firmware release. To do so, identify the operations link within the response, /mgmt/actionqueue/{domain}/operations. Access the operations link by substituting the appropriate {domain} value to retrieve the list of all currently supported operations on the DataPower Gateway as shown in the following request. Here, the target domain is set to test-domain. The list of supported operations in a release is the same, regardless of the {domain} value that is set. In this case, {domain} is required to ensure that you have appropriate access permissions to the target domain.

GET https://dphost.com:5554/mgmt/actionqueue/test-domain/operations

The response that is returned from the actionqueue operations URI shows all supported operations on the DataPower Gateway in the current firmware release. Listing 3 shows a partial response payload to this request.

Currently supported operations

 {
   "_links": {
     "self": {
       "href": "/mgmt/actionqueue/test-domain/operations"
     },
     "AddKnownHost": {
       "schema": {
         "href": "/mgmt/actionqueue/{domain}/operations/AddKnownHost"
       },
       "metadata": {
         "href": "/mgmt/metadata/{domain}/operations/AddKnownHost"
       }
     },
     "AddPasswordMap": {
       "schema": {
         "href": "/mgmt/actionqueue/{domain}/operations/AddPasswordMap"
       },
       "metadata": {
         "href": "/mgmt/metadata/{domain}/operations/AddPasswordMap"
       }
     },
     "AddSelTestEntry": {
       "schema": {
         "href": "/mgmt/actionqueue/{domain}/operations/AddSelTestEntry"
       },
       "metadata": {
         "href": "/mgmt/metadata/{domain}/operations/AddSelTestEntry"
       }
     },
     ...
 }

Search the response payload that is displayed in Listing 3 for the operation of interest. 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. If the operation is in the returned list, it is supported and can be triggered by using the REST management interface. You can access the schema and metadata embedded links to retrieve additional information about the required parameters for an operation. You might find this practice helpful while 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. Three resources are available to help you construct a valid payload: the schema resource of the REST management interface, the metadata resource of the REST management interface, and the DataPower SOMA schema. You can choose which approach to use to construct a valid payload because you are not required to consult all three sources.

The schema resource of the REST management interface is intended to provide a valid schema document for an operation. In the DataPower 7.2.0.0 firmware release, the functionality of the schema resource is not implemented and does not provide a schema that is suitable for payload validation. However, it provides a guideline document for structuring supported operation requests. To access this guideline document, use the schema link, which is shown in Listing 2 and Listing 3 as /mgmt/actionqueue/{domain}/operations/{operation}. Then, append a query parameter of schema-format=datapower to the URI. The following example shows this request for the AddPasswordMap DataPower operation:

GET https://dphost.com:5554/mgmt/actionqueue/test-domain/operations/AddPasswordMap?schema-format=datapower

Currently, the response is a modified schema document for the DataPower operation. This response is not valid for payload validation and is meant only to help you manually create a valid request payload. The response contains a list of all required parameters, their name formats, and types as shown in Listing 4 for the AddPasswordMap operation.

Schema aid document

 {
   "_links": {
     "self": {
       "href": "/mgmt/actionqueue/test-domain/operations/AddPasswordMap"
     },
     "doc": {
       "href": "/mgmt/docs/actionqueue/operations/AddPasswordMap"
     }
   },
   "AddPasswordMap": {
     "AliasName": {
       "minOccurs": 1,
       "maxOccurs": 1,
       "simpleType": {
        ...
       }
     },
     "Password": {
       "minOccurs": 1,
       "maxOccurs": 1,
       "simpleType": {
        ...
       }
     }
   }
 }

To supplement the information from the schema resource of the REST management interface (Listing 4), you can examine the operation's metadata from the metadata resource of the REST management interface. You can access the operation metadata by using the metadata link that is shown in Listing 2 and Listing 3 as /mgmt/metadata/{domain}/operations/{operation}. To retrieve the operation metadata, for {domain}, substitute test-domain, and for {operation}, substitute AddPasswordMap, as shown in the following request. The information that is retrieved from the schema and metadata resources is the same regardless of the {domain} identifier. In this case, the {domain} is required to ensure that you have access permissions to the target domain.

GET https://dphost.com:5554/mgmt/metadata/test-domain/operations/AddPasswordMap

The response that is returned from the metadata request might be large, depending on the target operation. The relevant information for constructing a request payload is in the parameters element of the response, as shown in Listing 5 for the AddPasswordMap operation. All target operation parameters are in this list, along with information about minimum and maximum values, required parameters, and type values.

Operation metadata retrieval 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": "QWRkcyBhIHBhc3N3b3JkIHRvIHRoZ..."
   }
 }

To further supplement the information that is retrieved from the schema resource and metadata resource of the REST management interface in Listing 4 and Listing 5, you can also examine the operation's SOMA schema. The SOMA schema for all operations is available on the DataPower from the default domain inside the store:///xml-mgmt.xsd file. When you search for the operation name, you see a schema similar to the example in Listing 6 for the AddPasswordMap operation. You can see the relevant information, such as which parameters are required, for constructing a request payload for the REST management interface by examining the minOccurs and maxOccurs attributes.

SOMA schema for an operation

 <xsd:complexType name="ActionAddPasswordMap">
   <xsd:sequence>
     <xsd:element name="AliasName" minOccurs="1" maxOccurs="1">
       <xsd:simpleType>
         <xsd:union memberTypes="tns:dmString tns:dmEmptyElement" />
       </xsd:simpleType>
     </xsd:element>
     <xsd:element name="Password" minOccurs="1" maxOccurs="1">
       <xsd:simpleType>
         <xsd:union memberTypes="tns:dmString tns:dmEmptyElement" />
       </xsd:simpleType>
     </xsd:element>
   </xsd:sequence>
 </xsd:complexType>

Relying on the schema and metadata resource capabilities for the REST management interface and on the DataPower SOMA schema can help you identify the required parameters to trigger an operation and the parameter names for the request payload. By using this information, a JSON request payload is structured according to the general guideline shown in Listing 7.

Operation payload 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. Listing 8 shows a valid payload to trigger the AddPasswordMap operation.

Valid operation payload

 {
   "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 domain actionqueue resource, /mgmt/actionqueue/{domain}. The following POST request shows how to trigger the AddPasswordMap operation in the test-domain.

POST https://dphost.com:5554/mgmt/actionqueue/test-domain

If the operation completed successfully, you see a confirmation response similar to the one in Listing 9 for the AddPasswordMap operation.

Operation response

 {
   "AddPasswordMap": {
     "_links": {
       "self": {
         "href": "/mgmt/actionqueue/test-domain"
       },
       "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 DataPower default log. One possible cause of failure is schema validation, as shown in Listing 10. This failure is caused by sending an improperly structured payload to trigger the operation.

Operation error

 {
   "_links": {
     "self": {
       "href": "/mgmt/actionqueue/test-domain_1"
     }
   },
   "error": [
     "Schema validation failure. Please check the operation schema and default log for more information."
   ]
 }

Conclusion

In this tutorial, you learned about operations on the IBM DataPower Gateway. You learned how to determine which operations are supported in a firmware release, how to compose a valid request payload for an operation, and how to trigger operation execution.

You have now completed this series of tutorials. With this last part, Part 4, you should now understand how to use the REST management interface to manage and monitor the configuration of the IBM DataPower Gateway.

Resources

See the other parts in this series:

• REST management interface and IBM DataPower Gateway, Part 1: Introduction to the interface and status monitoring
• REST management interface and IBM DataPower Gateway, Part 2: Configuration management
• REST management interface and IBM DataPower Gateway, Part 3: File and directory management
• REST management interface and IBM DataPower Gateway, Part 4: Triggering appliance operations

The following links are helpful when reading this article:

• To get started with the REST management interface, see Enabling the REST management interface.
• For everything related to the REST management interface, see REST management interface.
• For example requests and responses from the REST management interface, see Samples that use the REST management interface.
• For DataPower Gateway documentation, see the IBM Documentation.