Get started with the IBM MQ messaging REST API

The IBM MQ messaging REST API offers a convenient mechanism to exchange messages. While it is not as feature-rich as APIs such as the MQI and JMS, the REST API provides essential functionality, enabling you to produce and consume messages from a queue. Additionally, it simplifies the client implementation, requiring less client configuration, making it quick and easy to get started with.

The following diagram illustrates how the REST client interacts with the REST server and the queue manager.

The IBM MQ REST API application runs in a Liberty Server, called ‘mqweb’, which exposes the HTTP endpoints to allow communication between the client and queue manager. The REST client connects into Liberty over port 9443 and depending on whether the queue manager is local or remote, it connects to the REST server either in bindings mode or in client mode over TCP/IP. The client application can then make a HTTP request like ‘POST’ to produce a message onto the queue and ‘DELETE’ to destructively consume a message from the queue.

The messaging REST API is different from the administrative REST API, which is used to administer IBM MQ objects, such as queue managers, queues, and Managed File Transfer components.

In this tutorial we’ll explore how to use the messaging REST API in your applications so that they can interact with the queue manager to produce or consume messages.

This tutorial uses the latest version of the API, IBM MQ REST API V3. This version adds the ability to specify user-defined message properties and to include message priority. The ibm-mq-md-priority and ibm-mq-usr request headers are only available with REST API V3. Another difference between the previous versions and V3 is that the ibm-mq-md-correlationId request header has a different format in REST API V3. The header can be an application-specific ID or, if an encoded string requires the ID: prefix.

Part 1. Validating the availability of the IBM MQ REST service endpoint

cURL commands are a simple way to interact with a REST endpoint and can be used as a test to check your queue manager's REST configuration. These commands can include the three basic HTTP methods used by IBM MQ messaging REST API to allow applications to interact with MQ:

• POST is used to produce messages on to a specified queue hosted on a queue manager. For REST API V3, if your POST request contains user-defined messages, or application-specific correlation ID, the message is formatted as a JMS TextMessage.
• GET is used to browse messages on a specified queue hosted on a queue manager
• DELETE is used to destructively consume messages from a specified queue hosted on a queue manager

Check out this tutorial on IBM Developer for more information about cURL.

Prerequisites

Curl, which is a command line tool and library for transferring data with URLs.

Steps

Step 1. Set up your queue manager

The following instructions assume you are using MQ in a local container based on the IBM MQ Advanced for Developers image

Use the Ready, Set, Connect tutorials to set up your queue manager and get your container running. Then, skip to Step 3.

Step 2. Configure the mqweb server

If you are using a container that is based on the MQ Advanced for Developers container image you can skip this step.

If you are using a VM, a bare metal installation, or a customized container image, you will likely need additional configuration.

Go to Getting started with the messaging REST API topic in the IBM MQ docs to set up the MQ REST API. If you also need to set up the IBM MQ Console, check out the Getting started with the IBM MQ Console topic too.

If you’re using the MQ Operator on OpenShift, use this doc to configure IBM MQ Console.

If you’re using the container with Helm, then visit this docto supply custom web console configuration.

Step 3. Put a message on the queue using cURL

You can try out the MQ messaging REST API by using cURL to put messages on a queue.

Make sure that you have curl installed:

curl -V

You should see output that looks like this:

If you get an error saying, “command not found” or “curl not recognized”, this could suggest that curl is not installed on your machine. Please visit this website to install curl.

The MQ messaging REST API expects the following basic details in the POST request that will put a message on a queue:

• -k. This option allows you to connect to a server that has a self-signed certificate, not a CA issued one.
• -i. This option includes the response headers in the output (optional).
• request URL should be specified in the following format: https://host:port/ibmmq/rest/v3/messaging/qmgr/your_qm_name/queue/your_queue_name/message.

Issue the cURL POST command that will put a message to a queue. The following cURL command uses the default configuration for the MQ advanced for developer image, edit the command if your configurations differ.

curl -i -k https://localhost:9443/ibmmq/rest/v3/messaging/qmgr/QM1/queue/DEV.QUEUE.1/message -X POST -u app:passw0rd -H "ibm-mq-rest-csrf-token: blank" -H "Content-Type: text/plain;charset=utf-8" -d "Hello World"

• -X. This option specifies the request method.
• -u. This option is the name and password of the user that you added in the mqwebuser.xml file.
• -H. This option is the two header values, for the cross-site request forgery token and the content type for the message.
• -d. This option is the data or the message payload.

You should see output like this:

Well done!

If your output message looks like the one here, you've successfully used cURL to produce a message on to the queue. See if you can consume the message off the queue by using a similar command in the next step.

Step 4. Using the IBM MQ REST API to consume a message from the queue

The MQ messaging REST API expects the following basic details in the DELETE request that will destructively consume a message from a queue:

• -k. This option allows you to connect to a server that has a self-signed certificate, not a CA issued one.
• -i. This option includes the response headers in the output (optional).
• request URL should be in the following format: https://host:port/ibmmq/rest/v3/messaging/qmgr/your_qm_name/queue/your_queue_name/message.

Issue the cURL DELETE command that will destructively consume a message from a queue. The following cURL command uses the default configuration for the MQ advanced for developer image, edit the command if your configurations differ.

curl -i -k https://localhost:9443/ibmmq/rest/v3/messaging/qmgr/QM1/queue/DEV.QUEUE.1/message -X DELETE -u app:passw0rd -H "ibm-mq-rest-csrf-token: blank"

• -X. This option specifies the request method.
• -u. This option is the name and password of the user that you added in the mqwebuser.xml file.
• -H. This option is the two header values, for the cross-site request forgery token and the content type for the message.

You should see output like this:

Well done! If your output message looks like the one here, you've successfully used cURL to consume your message from the queue.

Step 5. (Optional) Use the Swagger UI to interact with the MQ messaging REST APIs

The mqweb server provides an option for switching on the API Discovery feature.

To use the swagger documentation, you will need to configure the mqweb.xml file:

If you are using a container, based on the MQ Advanced for Developers image, you cannot edit this file directly in the running container. Instead, you will need to copy the mqweb.xml file to a local host directory:

podman cp QM1:/opt/mqm/web/mq/etc/mqweb.xml path/to/local/directory

Open the .xml file in an editor and add the following line inside the featureManager tags:

<featureManager>
<feature>apiDiscovery-1.0</feature>
</featureManager>

Then, copy the edited mqweb.xml back to its original directory:

podman cp path/to/local/directory/mqweb.xml QM1:/opt/mqm/web/mq/etc/

You can now use the Swagger documentation by pointing your browser to: https://host:port/ibm/api/explorer, such as:

https://localhost:9443/ibm/api/explorer

Then, use the Swagger UI to interact with the REST APIs. You can produce and consume messages from the "messaging REST API" and see the queue depth change in the MQ Console for the queue DEV.QUEUE.1.

Or, you can point your browser to: https://host:port/ibm/api/docs. Then, retrieve a Swagger 2 document that describes the whole REST API, for example:

https://localhost:9443/ibm/api/docs

Part 2. Examples that use the IBM MQ REST API in Rust, Golang, and Node.js

cURL is a simple and useful tool to check the IBM MQ REST endpoint’s availability, however as a developer you may want to build a more sophisticated application with a richer framework.

To get you started we have some examples that use the REST API:

• Rust example
• Go example
• Node.js examples

Prerequisites for the examples

• Rust
• Node.js Runtime
• Go Runtime

Rust example that uses the MQ messaging REST API

The Rust example is in the mq-dev-patterns repository, which contains all the current samples for IBM MQ. By cloning it you will have access to several other samples in different languages ready to be tested and used. We will be focusing on the /Rust-REST/ section of this repository.

At a command prompt, issue this command to clone the repo:

git clone https://github.com/ibm-messaging/mq-dev-patterns.git

Navigate to the mq-dev-patterns directory, and then to the Rust-REST directory. You will run the Rust sample programs from this directory.

If you want to connect to a pre-existing IBM MQ queue manager using this Rust sample, you must first update the envrest.json file to specify the APP_USER, APP_PASSWORD, HOST, and PORT values. If you are using a queue manager on IBM Cloud, follow the instructions in the IBM MQ on Cloud docs.

You're now ready to send an MQ message via the IBM MQ REST API with this Rust sample.

Next, we will send a message to your IBM MQ queue manager using Rust.

As a first step, you can check if your queue manager is successfully handling messages by executing this command.

On macOS or Linux:

./RUNME.sh

On Windows:

bash RUNME.sh

This script file will execute consecutively the sender and receiver samples found inside the cloned repository.

The output from running this script file looks like this:

And this:

After a successful execution of both the POST and GET programs, an HTTP status code of 201 will be displayed for the POST sample and 200 for the DELETE sample. These are based on the outcome of the request.

Go example that uses the MQ messaging REST API

This example is available in our mq-dev-sample repository, if you navigate to the ‘gettingStarted folder you will see our messaging REST sample, which includes the Go example.

The queue manager that the application, in this example, looks to communicate with is running in IBM Cloud. The default SSL HTTP port for queue managers running in IBM Cloud is 9443. A user can specify a different port, but if no port is available, the default port will be used.

In this application, put and get calls are wrapped in Go functions. The request URL for the queue manager, qmURL, is constructed to include the host, port, the default path for the messaging REST API, queue manager name, and queue name.

The request is then created, the message type is set and additional parameters that we used in our cURL calls earlier are added; the CSRF token, the content type and user and password for authentication.

The sender and receiver samples that are a part of this application pass on the correct MQ parameters to this method and the REST call is constructed and sent.

Node.js examples that use the HTTPS or Promise modules

For more examples using Node.js, you can visit our github repository. One example uses a basic HTTPS module to exchange messages. Another example shows you how to use JavaScript promises so the REST calls are in the right sequence.

Summary and next steps

Congratulations! You can REST easy now that you've produced and consumed your messages.

To understand more about the API you can visit this this website and the IBM documentation. Additionally, you can visit our github repository and view our IBM MQ Showcase App, which uses the REST API and explore how the API is integrated here.