One of several new features in the MQ REST API in V9.0.4 is the REST API gateway. This allows you to administer queue managers on different systems, and at different versions of MQ, through the REST API.

Background

The MQ administrative REST API was first added in MQ V9.0.1, and since then more capabilities have been added to the REST API in each version. It gives you an easier interface to issue administrative commands that can be used by any application capable of issuing HTTP requests.

However, until now, the queue managers that could be administered through the REST API has been fairly limited. In order to be accessible through the REST API, queue managers had to be:

  • Running on the same system as the mqweb server, and
  • In the same installation as the mqweb server on distributed platforms, or
  • At the same MQ version as the mqweb server on z/OS.

As a reminder, the mqweb server is the Liberty server that runs both the MQ Console and REST API. It’s an optional part of the MQ installation since MQ V9.0.1.

From MQ V9.0.4, you can administer a much wider range of queue managers. The REST API gateway allows you to administer queue managers running on remote systems, as well as queue mangers running older versions of MQ. This gives you two big benefits. You won’t need a mqweb server running on every system where you have queue managers that you want to manage through the REST API any more, and as long as you have at least one MQ V9.0.4 queue manager, you can now use the REST API to administer your V8 and V9 Long Term Service Release (LTSR) queue managers.

How do I set this up?

You still need at least one queue manager that the REST API can connect to directly. This is the gateway queue manager, from which commands can be sent on to other queue managers. The diagram below should better illustrate this configuration.

The gateway queue manager needs to be running on the same system, and be in the same installation as the mqweb server (on distributed platforms), or running at the same version as the mqweb server (on z/OS).

You then need to set up communications between the gateway queue manager and any remote queue managers that you want to administer. Essentially, this means defining a pair of channels, and associated transmission queues, to allow messages containing PCF commands to flow to the remote queue manager, and for the responses to return to the gateway queue manager. Preparing queue managers for remote administration in the MQ Knowledge Center describes this in more detail.

The diagram below shows how a command issued by the mqweb server gets routed to a remote queue manager, and the response returned.

Finally, if you want to configure a default gateway queue manager, set the mqRestGatewayQmgr property in the mqwebuser.xml configuration file to the name of the gateway queue manager. This default gateway queue manager will be used for every REST API request to a remote queue manager, unless the request specifies another gateway queue manager (see below for how that’s done). You can set this property with the setmqweb command added in MQ V9.0.4, rather than editing the mqwebuser.xml file manually. For example:
setmqweb properties -k mqRestGatewayQmgr -v QM01

What about security?

Setting up security correctly is key to getting the REST API gateway working. User IDs that use the REST API gateway to manage remote queue managers must exist on the remote system, be authorized to inquire the remote queue manager, and have access to the transmission queues used for communication between the gateway and the remote queue managers. This is, of course, in addition to the authority needed on the remote system to issue the command required to perform the REST request itself.

What resources can I manage using the REST API gateway?

At the moment only queue managers, queues and subscriptions can be managed using the REST gateway, and only a subset of the queue manager attributes are returned for remote queue managers accessed through the REST gateway.

How do applications use the REST API gateway?

If a default gateway queue manager has been configured, applications can simply use the REST API as they do today, specifying the name of the remote queue manager in the URL. The name of the gateway queue manager used for the request will be returned in the ibm-mq-rest-gateway-qmgr HTTP header.

Below is an example REST API request from a Windows machine to a remote queue manager running on z/OS, and the response.

GET https://localhost:9443/ibmmq/rest/v1/admin/qmgr/MQZ1?status=*

ibm-mq-rest-gateway-qmgr:  RESTQM0

{"qmgr": [{
  "name": "MQZ1",
  "status": {
    "channelInitiatorState": "running",
    "connectionCount": 73,
    "publishSubscribeState": "running",
    "started": "2017-10-30T11:10:45.000Z"
  }
}]}

If no default gateway queue manager has been configured, applications can use the REST API gateway by setting the ibm-mq-rest-gateway-qmgr HTTP header to the name of the gateway queue manager name in the request.

Bear in mind that only parameters and attributes that are valid on the remote platform will be valid on the REST request. For example, if the remote platform is Windows, it will be invalid to specify the queueSharingGroupDisposition parameter on a request, even if the mqweb server is running on z/OS, as you can see in the following example.

GET https://mvs01.hursley.ibm.com:9486/ibmmq/rest/v1/admin/qmgr/RESTQM0/queue?queueSharingGroupDisposition=shared

ibm-mq-rest-gateway-qmgr:  MQZ1

{"error": [{
  "action": "Resubmit the request without this query parameter.",
  "completionCode": "0",
  "explanation": "The named parameter is platform-specific and not applicable to the platform that the queue manager runs on.",
  "message": "MQWB0026E: The parameter 'queueSharingGroupDisposition' is not applicable to queue managers on the 'Windows' platform.",
  "msgId": "MQWB0026E",
  "reasonCode": "0",
  "type": "rest"
}]}

More information

There’s more information on the REST gateway in the MQ Knowledge Center.

Leave a Reply