Part 1: Introduction to the REST management interface and status monitoring

Content

Introduction

The REST management interface, as implemented in firmware release 7.2.0.0, provides another means of retrieving configuration and status resources from the IBM DataPower Gateway appliance. These resources can be created, updated, fetched, or deleted (as supported) by using a modern and intuitive REST-based API. The goal of the REST management interface is to provide equivalent functionality to the familiar DataPower Service-Oriented Management Interface (SOMA). At the same time, the REST management interface emphasizes additional capabilities, such as intuitive and quick resource discovery and navigation, enhanced user experience, and detailed error reporting.

Part 1 in this series introduces the REST management interface and shows the general structure of its resources. It describes specific requests to retrieve information from status providers. It also describes considerations for using the first REST management interface release, in comparison to the existing SOMA interface. Parts 2 – 4 of this series highlight other request types, such as configuration management, file and directory management, and appliance operations. These parts include common use cases to help you determine whether the REST management interface is suitable for your needs.

Enabling the REST management interface

To manage the DataPower appliance through the REST management interface, you must first enable the REST management interface through one of the other appliance interfaces. By default, the REST management interface and all other appliance interfaces are disabled. You can find instructions on how to enable the REST management interface in Enabling the REST management interface.

URIs and payloads

This section helps to enhance your understanding of REST management interface functionality and the process of constructing valid requests. It describes the Uniform Resource Identifier (URI) hierarchy of the REST management interface and the overall structure and format of the request and response payloads. You can find detailed instructions on how to construct REST management interface requests for specific resource types in later sections.

Because this tutorial does not explain details about a particular REST client, choose a tool that is suitable to your own environment. For example, you might choose a command line utility, such as curl. Or, you might choose a web browser-based utility, such as the RESTClient for the Firefox browser or Postman for the Google Chrome browser.

URI hierarchy

You can obtain the list of all available DataPower Gateway Appliance resource categories by sending a GET request to the REST management interface root URI:

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

Listing 1 shows the response that is received from the root URI of the REST management interface. This list presents the available resource categories on the appliance. You can access individual resource URIs by issuing requests to the embedded href links, which include a trailing forward slash (/) character. The trailing / character must be present only in top-level URIs that represent the available resource categories. Listing 1 shows these URIs. The trailing / character is not allowed on all other URIs because it results in an error.

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

Each of the top-level resources that are shown in Listing 1 shows the following domain-specific resources. These resources can also serve as URI targets to trigger management operations.

• Configuration management root URI:/mgmt/config/

  This resource is the entrance point for configuration management operations, such as retrieving and updating existing configurations, creating new configurations, and deleting unused configurations. The configuration URI hierarchy is captured by the following URI structure:
  /mgmt/config/{domain_name}/{class_name}/{object_name}/{property_name}

• Quick reference URI of the application domains: /mgmt/domains/config/

  This resource is a GET only URI that returns a list of currently existing domains on the appliance.

• Status provider root URI:/mgmt/status/

  This resource is the entrance point for status provider data retrieval. The status URI hierarchy is captured by the following URI structure:
  /mgmt/status/{domain_name}/{class_name}/{property_name}

• Appliance operations root URI: /mgmt/actionqueue/

  This resource is the entrance point to the appliance management operations capabilities, the listing of supported operations, and for triggering supported operations within an application domain. The actionqueue URI hierarchy is captured by the following URI structure:
  /mgmt/actionqueue/{domain_name}/operations/{operation_name}

• Filestore management root URI: /mgmt/filestore/

  This resource is the entrance point to the appliance file and directory management capabilities. These capabilities include retrieving the contents of existing files and directories, updating existing files, and deleting unused files and directories. All files and directories, including RAID contents, are accessible through the filestore resource, if you have access permissions to the specified resource. The filestore URI hierarchy is captured by the following URI structure: /mgmt/filestore/{domain_name}/{directory_path}/{file_name}

• Metadata retrieval root URI:/mgmt/metadata/

  This resource is the entrance point to the appliance metadata resource for configuration objects and operations. It returns information about the configuration structure, required parameters, default values, and descriptions for individual parameters. This information can be helpful in your understanding of the structure of an object or operation to construct a valid request payload. The metadata URI hierarchy is captured by the following URI structure: /mgmt/metadata/{domain_name}/{class_name}/{property_name}

• Type retrieval root URI:/mgmt/types/

  This resource is the entrance point to the appliance type resource for all existing appliance types. It returns information about individual type specifications and can be helpful in your understanding of the allowed values for configuration parameters in request payloads. The type URI hierarchy is captured by the following URI structure: /mgmt/types/{domain_name}/{type_name}

To access these appliance resources, you must substitute the appropriate values for parameters, such as {domain_name}, {class_name}, {object_name}, and {property_name}, that are in braces. Also, to access all domains on the appliance, including the default domain, you set the {domain_name} identifier within the URI to the domain of interest. For the /mgmt/metadata/ and /mgmt/types/ resources, the information that is returned is the same regardless of the specified domain name. In this case, the {domain_name} identifier is required within the URI to ensure that you have access permissions to the target domain.

Request and response conventions

The REST management interface uses the standard HTTP methods of GET, POST, PUT, DELETE, and OPTIONS. However, not every resource is available in all HTTP methods. For example, status resources support only the GET method, where configuration resources allow more supported methods. You can retrieve the list of supported HTTP methods on any URI by sending the OPTIONS request to that URI.

The request and response payloads of the REST management interface are in JSON only and conform to a specific schema. The payload schema is derived from the existing appliance SOMA schema, which is documented in store:///xml-mgmt.xsd. You can find detailed instructions on how to construct valid REST management interface requests for different resource types in the following sections of this tutorial. A basic authentication header must be present in every request that is sent to the REST management interface.

The response payload that is returned by the interface partially conforms to the Hypertext Application Language standard. This format was chosen for its apparent acceptance, robustness, and ease of human readability. It was also chosen to enhance your understanding and navigation of the API because it includes all available resources from any point within the API. It includes the resources by embedding an _links element within the JSON response, which contains pointers to accessible resources, including possible documentation. You can then target the resources within the _links element in your subsequent REST management interface requests. Listing 2 shows an example that contains an embedded _links element to the current resource, within the self link, and the associated documentation, within the doc link. The documentation links are not fully supported in the DataPower Gateway 7.2.0.0 release.

   {     "_links": {     "self": {       "href": "/mgmt/status/default/FirmwareVersion"     },     "doc": {       "href": "/mgmt/docs/status/FirmwareVersion"     }   },   "FirmwareVersion": {     "Serial": xxxxxxx,     "Version": "XI52.7.2.0.0",     "Build": "xxxxxxx",     "BuildDate": "2015/04/27 10:27:07",     "WatchdogBuild": "XI52.7.2.0.0",     "InstalledDPOS": "XI52.7.2.0.0",     "RunningDPOS": "XI52.7.2.0.0",     "XMLAccelerator": "embedded",     "MachineType": 7199,     "ModelType": "42X"   } }

A key need is monitoring the DataPower Gateway Appliance. The REST management interface offers end-to-end monitoring capabilities in the DataPower Gateway 7.2.0.0 firmware release. You can retrieve complete status provider data for all existing status provider classes and retrieve individual property values of each status provider. The following sections describe the process of retrieving status information.

To begin retrieving the required status provider data from the appliance, first identify the specific status provider class that you need. To identify the required status class name, access the REST management interface root URI, as shown in the GET request in URI hierarchy, to identify the status root URI. In the received response, shown in Listing 1, identify the status root URI as /mgmt/status/. Then, to retrieve a list of all available status provider classes on the appliance, access /mgmt/status/:

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

To identify the exact formatting of the status provider class name, you search the received response payload, which is partially shown in Listing 3.

 {   "_links": {     "self": {       "href": "/mgmt/status/"     },     "ActiveUsers": {       "href": "/mgmt/status/{domain}/ActiveUsers"     },     "Battery": {       "href": "/mgmt/status/{domain}/Battery"     },     "ConnectionsAccepted": {       "href": "/mgmt/status/{domain}/ConnectionsAccepted"     },     "CPUUsage": {       "href": "/mgmt/status/{domain}/CPUUsage"     },     "CryptoEngineStatus2": {       "href": "/mgmt/status/{domain}/CryptoEngineStatus2"     },     "CryptoHwDisableStatus": {       "href": "/mgmt/status/{domain}/CryptoHwDisableStatus"     },     "CryptoModeStatus": {       "href": "/mgmt/status/{domain}/CryptoModeStatus"     },     ...   }   }  

As an alternative to identifying the formatting of the status provider class, you can examine the URI that is shown in the WebGUI browser window whenever a specific status provider is accessed.

After you identify the desired status provider class name, you can retrieve the associated status data. To retrieve the data, you construct a URI of the form /mgmt/status/{domain}/{class_name}, replacing {domain} with the target domain and {class_name} with the desired status provider class. The following request shows a URI to retrieve information from the CPUUsage status provider within the default domain:

GET https://dphost.com:5554/mgmt/status/default/CPUUsage  

Listing 4 shows the status data that is returned from the CPUUsage status provider.

 {   "_links": {     "self": {       "href": "/mgmt/status/default/CPUUsage"     },     "doc": {       "href": "/mgmt/docs/status/CPUUsage"     }   },   "CPUUsage": {     "tenSeconds": 23,     "oneMinute": 24,     "tenMinutes": 22,     "oneHour": 23,     "oneDay": 23     }   }  

The following request shows a URI to retrieve information from the DataTimeStatus status provider within the default domain:

GET https://dphost.com:5554/mgmt/status/default/DateTimeStatus  

Listing 5 shows the status data that is returned from the DateTimeStatus status provider.

 {   "_links": {     "self": {       "href": "/mgmt/status/default/DateTimeStatus"     },     "doc": {       "href": "/mgmt/docs/status/DateTimeStatus"     }   },   "DateTimeStatus": {     "time": "Sun Sep 7 16:18:09 2014",     "timezone": "EDT",     "tzspec": "EST5EDT,M3.2.0/2:00,M11.1.0/2:00",     "uptime2": "2 days 14:27:38",     "bootuptime2": "133 days 01:01:34"   } }  

You can also retrieve the value of a specific status provider property, instead of retrieving the status provider output in its entirety. To retrieve the value, you construct a URI of the form /mgmt/status/{domain}/{class_name}/{property_name}. You replace {domain} with the target domain, {class_name} with the desired status provider class, and {property_name} with the specific property name as it appears in the complete status provider response, as shown in Listing 4 and Listing 5.

The following request shows a URI to retrieve property information from the CPUUsage status provider within the default domain. The value of the tenMinutes property is being retrieved.

GET https://dphost.com:5554/mgmt/status/default/CPUUsage/tenMinutes

Listing 6 shows the status data that is returned from the CPUUsage status provider property tenMinutes.

 {   "_links": {     "self": {       "href": "/mgmt/status/default/CPUUsage/tenMinutes"     },     "doc": {       "href": "/mgmt/docs/status/CPUUsage/tenMinutes"     }   },   "CPUUsage": {     "_links": {       "self": {         "href": "/mgmt/status/default/CPUUsage"       },       "doc": {         "href": "/mgmt/docs/status/CPUUsage"       }     },     "tenMinutes": 22   } }  

The following request shows a URI to retrieve property information from the DateTimeStatus status provider within the default domain. The value of the timezone property is being retrieved.

GET https://dphost.com:5554/mgmt/status/default/DateTimeStatus/timezone  

Listing 7 shows the status data that is returned from the property timezone of the DateTimeStatus status provider.

 {   "_links": {     "self": {       "href": "/mgmt/status/default/DateTimeStatus/timezone"     },     "doc": {       "href": "/mgmt/docs/status/DateTimeStatus/timezone"     }   },   "DateTimeStatus": {     "_links": {       "self": {         "href": "/mgmt/status/default/DateTimeStatus"       },       "doc": {         "href": "/mgmt/docs/status/DateTimeStatus"       }     },     "timezone": "EDT"   } }  

To improve the overall user experience, navigation, and level of adoption of the REST management interface that is available in DataPower firmware release 7.2.0.0, keep in mind several considerations.

First, the REST management interface supports only a select set of operations. You can retrieve the list of supported operations as explained in Listings 5 and 6 in Part 4 of this series. If an operation is not currently supported through the REST management interface, you can use another interface to trigger the operation.

Second, documentation through the embedded /docs links within the response payloads of the REST management interface is not currently available. However, it will be included in a future release to provide better in-context information and to improve your experience. For now, current information about the REST management interface is available only in the IBM DataPower Gateway documentation.

Third, all requests and responses are in English only. Modifying the locale setting on the appliance does not affect the response format of REST management interface. That is, the response is not translated based on the appliance locale.

Conclusion

In this tutorial, you learned about the REST management interface that was implemented in firmware release 7.2.0.0 for IBM DataPower Gateway. You learned how to enable the interface and learned about the URI and payload structure of the REST management interface. You also learned how to retrieve information from status providers, specifically from all DataPower status providers. As you continue in this tutorial series, Part 2 explains how to use the REST management interface to manage and monitor the configuration of DataPower Gateway appliances.

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 tutorial:

• 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 SOA Appliances 7.2.0 documentation, see the IBM Knowledge Center.
• For DataPower tutorials in the IBM developerWorks WebSphere zone, see the Technical Library.
• For the latest news and information, see the IBM developerWorks WebSphere zone.