Invoking the queue manager REST APIs

IBM MQ provides a set of REST APIs that provide a simple way to administer, test and interact with your queue manager via scripts, applications and programs. In this section, the requirements to call the APIs on the IBM queue manager will be provided, in addition to examples that can be run straight from your terminal and be easily translated into other programming languages.

An IBM queue manager has 2 REST APIs available to call:

Administration REST API - that allows you carry out administrative actions against the queue manager
Messaging REST API - that allows applications to send and receive messages

There are a few important pieces of information when interacting with the IBM queue manager:

The Listener Port is not required in the URI to call the REST API
The hostname to call your queue manager should start with web-
The beginning of the path in the URI should be /ibmmq/rest
The REST API is case-sensitive - for example if your queue manager is called QM1 and your using the admin REST API, then in the path for admin you should do /qmgr/QM1/...

Authenticating your client to invoke REST API requests

There are a couple of ways that you can authenticate with your IBM queue manager over REST.

The method described below is token-based authentication, interacting with the Login REST API exposed by the queue manager. This REST API returns a cookie that can be saved to a variable in your script/application or in a plain text file that can be used by subsequent requests to your queue manager.

Once you have finished interacting with the IBM queue manager over REST, the Login REST API can also be used to revoke the access token, requiring the client to retrieve a new access token before making subsequent calls.

For more information on how to use token-based authentication to interact with your queue manager over REST see here.

Your queue manager hostname will differ per queue manager and per region, but will look similar to qm1-abcd.qm.eu-gb.appdomain.cloud

curl -X POST https://web-<queue_manager_hostname>/ibmmq/rest/v3/login -H "Content-Type: application/json" --data "{\"username\":\"<MQ_USERNAME>\",\"password\":\"<API_KEY>\"}" -c cookiejar.txt

In subsequent calls pass the cookiejar.txt file as a parameter to identify yourself as an authenticated user.

For more ways and information on how you can authenticate with your IBM queue manager over REST, see here

Administering the queue manager

The admin REST API enables the ability to administer the queue manager, allowing you to create, retrieve, modify and delete queues.

The admin REST API documentation can be found here.

Example: Creating a queue in an IBM queue manager

If you have authenticated using token-based authentication, point to the place you stored your cookie to identify yourself as an authenticated user.

curl -X POST https://web-<queue_manager_hostname>/ibmmq/rest/v3/admin/action/qmgr/<queue_manager_name>/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

You can then display the created queue by running the following command.

curl -X POST https://web-<queue_manager_hostname>/ibmmq/rest/v3/admin/action/qmgr/<queue_manager_name>/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

Sending and receiving messages

The messaging REST API allows you to send and retrieve messages on a desired queue within an IBM queue manager.

The messaging REST API documentation can be found here.

Non 'DEV.' queues

If a new queue has been created whose name does not start with 'DEV.' the predefined authorization records will not apply. Therefore applications will not have the required permissions to send or receive messages to this queue. Review the Assigning user/group access to a queue guide for more information and for the steps required to configure the authorization record required for this queue.

Example: Putting a message on a queue in an IBM queue manager

If you have authenticated using token-based authentication, point to the place you stored your cookie to identify yourself as an authenticated user.

curl -X POST https://web-<queue_manager_hostname>/ibmmq/rest/v3/messaging/qmgr/<queue_manager_name>/queue/<queue_name>/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" --data "hello world" -b cookiejar.txt

Please note that by default any messages sent via the messaging REST API will be treated as non-persistent, regardless of the target queue's configured default persistence setting. To change the default behaviour, you can include an optional header ibm-mq-md-persistence which must be specified as one of the following values: - persistent - nonPersistent

To send a persistent message, the example above would then take the following form:

curl -X POST https://web-<queue_manager_hostname>/ibmmq/rest/v3/messaging/qmgr/<queue_manager_name>/queue/<queue_name>/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" -H "ibm-mq-md-persistence: persistent" --data "hello world" -b cookiejar.txt

The full list of messaging REST API headers can be found here