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.

This topic describes the requirements for calling the APIs on the IBM queue manager. It also provides examples that can be run straight from your terminal and be easily translated into other programming languages.

An IBM MQ queue manager has two REST APIs available to call:

Administration REST API - enables you carry out administrative actions on the queue manager
Messaging REST API - enables applications to send and receive messages

There are a few important pieces of information when interacting with the IBM MQ 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 have /qmgr/QM1/...

Authenticating your client to invoke REST API requests

There are a couple of ways that you can authenticate with your IBM MQ 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.

When 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 Using token-based authentication with the REST API in the main IBM MQ documentation.

Your queue manager hostname will differ per queue manager and per region.

Example: Authenticating with an IBM queue manager using a session cookie

$ 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

Important: 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 Configuring client certificate authentication with the REST API and IBM MQ Console in the main IBM MQ documentation.

Administering the queue manager

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

The administrative REST API documentation can be found in the main IBM MQ product documentation, see https://www.ibm.com/docs/en/ibm-mq/latest?topic=reference-administrative-rest-api.

Example: Creating a queue in an IBM queue manager

If you have authenticated using token-based authentication, point to the location where 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 enables you to send and retrieve messages on a desired queue within an IBM MQ queue manager.

The messaging REST API documentation can be found in the main IBM MQ product documentation, see Messaging using the REST API.

Non 'DEV.' queues

If a new queue has been created whose name does not start with 'DEV.' the predefined authorization records do not apply. Therefore applications do not have the required permissions to send or receive messages to this queue. See Assigning user/group access to a queue 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

Note that, by default, any messages sent using the messaging REST API are treated as non-persistent, regardless of the target queue's configured default persistence setting. To change the default behavior, you can include an optional header ibm-mq-md-persistence, which must be specified as persistent or nonPersistent.

To send a persistent message, the previous example would 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 in the main IBM MQ product documentation, see /messaging/qmgr/{qmgrName}/queue/{queueName}/message.