MQ 9.0.4 continues to build on the features of the REST API introduced in version 9.0.1, this time giving you the ability to display channels in the same convenient way available for installations, queue managers and queues.
If you would like to know more about the numerous benefits that come with using the new administrative REST interface, you will find more information in this post by Mark Bluemel.

New endpoint, same structure

Following the structure already laid out for queues, the most plain and simple display channel request will look like this:
http://mq-server.ibm.com/ibmmq/rest/v1/admin/qmgr/QM1/channel

As you might expect, this will return a list of all channels on queue manager QM1, along with their name, type and any other relevant information displayed by default, such as connections. The result will be laid out as a JSON string like this:

 channel:[
  {
    “name”: “QM2.TO.QM1”,
    “type”: “receiver”
  },
  {
    “name”: “QM1.TO.QM2”,
    “type”: “sender”,
    “sender”: {
      “connection”: [
        {
          “host”: “mq-server.com”,
          “port”: 1414
        }
      ],
      “transmissionQueueName”: “QM2”
    }
  }
]

It is worth pointing out that connection is nested inside a “sender” object. By design, all attributes that are specific to a certain type of channel are embedded in a named object to make their type-specific nature more obvious.

You can also select channels with a certain name and type by adding name and type URL parameters, respectively. The resulting URL will look something like this:
…/qmgr/QM1/channel?name=SYS*&type=sender

The name parameter supports a single wildcard anywhere within the string: *START, MID*DLE and END* are all valid values.

As with queues, a URL is also provided for inquiring about a specific channel by name:
…/qmgr/QM1/channel/QM1.TO.QM2

This form of URL does not support name, type or channel attribute filtering as they would be redundant.

You GET what you ask for

Given the large amount of information available at the channel level, we figured it would be best to only display what the user is explicitly asking for. This makes the result more legible for both interactive use of the API and logging purposes.
You can customise your query by adding attributes and status (Yes, channel status can also be queried from this endpoint. More on that further down) parameters to your URL:
…/qmgr/MY.QM/channel?attributes=general.description,exits

The above request will return a JSON array with an object for each channel, containing a general object with a description attribute. The * and all shortcuts seen in queues to include all available attributes will also work with channels.

At this point, you might be wondering whether requesting type-specific parameters will require knowing all type names beforehand, with an attribute list such as sender.connection, clusterSender.connection, clusterReceiver.connection, requester.connection, server.connection, sender.transmissionQueueName….
That is why we are also providing a handy shortcut to include all channel types: [type]. For instance, a valid value for the attributes parameter could be [type].connection, or just [type].

For a complete list of all available attributes, you should refer to the IBM Knowledge Center.

Status as a property

If you have administered an MQ installation (more than likely considering you are reading this article) you will probably be familiar with the idea that channel information and channel status are two separate things: MQSC commands, for example, split them into CHANNEL and CHSTATUS.

The REST API, however, is centred around the idea of an object, without distinction between static and runtime properties. It was therefore intuitive to show status as being a property of the inquired object. This is not new to the API: queue objects work the same way.

Status attributes can be requested the same way as channel attributes, through a status URL parameter, with the only subtle difference of a further level of nesting, to distinguish between current status and saved status. Here is an example request, with sample output:
…/qmgr/QM1/channel/QM2.TO.QM1?status=currentStatus.state

channel: [
  {
    “name”: “QM2.TO.QM1”,
    “type”: “receiver”,
    “currentStatus”: [{
      “state”: “running”
    }]
  }
]

For a complete list of all available attributes, you should refer to the IBM Knowledge Center.

Can I try it out?

If you haven’t tried out the REST API yet, here you will find instructions on how to get going. Happy curling!

Leave a Reply