IBM MQ On Cloud as a REST Service
IBM MQ on Cloud is an IBM MQ service available as a PaaS in IBM Cloud. This article describes how to create a queue manager for IBM MQ on Cloud and access queue manager services as REST endpoints. IBM introduced REST services for IBM MQ starting in version 9.0.1.
Create MQ Resource
As a first step, create an account in IBM Cloud by going to IBM Cloud. I created a free account with the Lite plan. After the account is created, log in to IBM Cloud and search for MQ services. Select a location (IBM Datacenter), the Lite plan, accept the license agreement, and create a resource called MQ-rt.
Once MQ resource is created, select this resource (MQ-lr) from the resource list.
Create Queue Manager
On MQ-lr page, you will see TESTQM queue manager which I have already created. Let’s create another queue manager called QM.FOR.YOU.
Once you click on Create, deployment starts and could take about 10 minutes to complete.
Click on QM.FOR.YOU to see queue manager endpoints. Please note
- Hostname: qm-for-you-8b8e.qm.us-south.mq.appdomain.cloud
- Messaging endpoint: https://web-qm-for-you-8b8e.qm.us-south.mq.appdomain.cloud/ibmmq/rest/v2/messaging/qmgr/QM.FOR.YOU/queue/<queue_name>/message
- Admin endpoint: https://web-qm-for-you-8b8e.qm.us-south.mq.appdomain.cloud/ibmmq/rest/v2/admin/qmgr/QM.FOR.YOU
Click on Administration tab. You will see 3 options: MQ Console, MQ Explorer and runmqsc. Click on Launch MQ Console.
This is the new MQ Console. Here, you can manage queue manager, create queues, setup client applications to interact with the queue manager and download connection file.
Create Queue
Let’s create a queue called TEST.Q. Click on Create a queue tab, select local queue type and type the queue name and click on Create.
Click on Manage queue manager tab, you will see all the local queues and the queue we just created. To see system queues, click on “Click here to see how”.
Client Configuration
At this point, we should go back to MQ-lr page and create application credentials so the client application can connect to QM.FOR.YOU and put/get messages from TEST.Q.
On MQ-lr page, click on Application Credentials tab and click on Add
Type client application name as ‘mqclient’ and click on Add and generate API key.
API Key is successfully generated. It can be simply copied or downloaded.
Application name (mqclient) as username and API Key as password must be used when making a REST API call to connect to the queue manager.
Now with client application credentials created, it’s time to authorize the client to connect to the queue manager and put/get messages on the TEST.Q.
Go back to queue details page for TEST.Q in MQ Console.
Click on Actions on the top right corner and view configuration.
Click on Security tab and add a new authority record for client application ‘mqclient’.
Type username as ‘mqclient’ and select permissions for browse, inquire, get, put and set and add a record.
You will see a new auth record created for user ‘mqclient’.
Test using Postman
At this point, we are ready to test the queue manager and the queue. I’ll use postman for sending REST requests to put and get messages from TEST.Q.
Copy messaging endpoint provided earlier and configure postman as follows:
Select Basic Auth under Authorization tab with
- username = mqclient
- password = {API-Key}
and Body with ‘This is chary testing MQ on Cloud’
In addition, for any changes to MQ resources, CSRF header ‘ibm-mq-rest-csrf-token’ with an empty value must be added to HTTP header.
Click on Send, you will get a 201 created success message. This means message was successfully put on the queue. Let’s retrieve the same message using GET API.
Keep the same URL, change HTTP method to Get and remove message from body. Click Send. You should see the message retrieved with HTTP response code of 200 OK.
Test using MQ Explorer.
Go back to MQ-lr page, select the queue manager: QM-FOR-YOU and click on MQ Explorer tab.
Make a note of all the connection details you will need to configure MQ Explorer on this page.
- Hostname: qm-for-you-8b8e.qm.us-south.mq.appdomain.cloud
- Port number: 32415
- Server connection channel: CLOUD.ADMIN.SVRCONN
- Enable user identification: yes
- Administrator username: lineswsoc
Click on Create IBM Cloud Key. This key is required for administrator to connect to the queue manager. This key will need to be used as the password.
By default, channels are SSL enabled. You will need to configure SSL for MQ Explorer to connect to QM on cloud. Modify Cipher Spec of the channel CLOUD.ADMIN.SVRCONN to use TLS_RSA_WITH_AES_128_CBC_SHA256 in the channel’s SSL properties.
In addition, create an AUTH record for administrator user. In my case lineswsoc is the admin user. In Security tab of the channel properties page, add a new AUTH record for user: lineswsoc.
Now, on the machine where MQ Explorer is running, create a key store and import queue manager certificate.
Go to MQ-lr resource page. Click on the queue manager QM.FOR.YOU.
Click on Key Store tab, select the channel CLOUD.ADMIN.SVRCONN and download the certificate.
Run the following commands to create a key store in JKS format and add the downloaded cert. to the key store. Assign a password to the key store as well.
Now add a remote queue manager to MQ Explorer as shown below using connection details saved before.
Enable user identification and type administrator id in the userid field.
Enable SSL and select the JKS key store that we created in the previous step.
Enable SSL options and choose the same cipher spec: TLS_RSA_WITH_AES_128_CBC_SHA256 and click finish.
You will be prompted for two passwords: first one is for JKS keystore and second one is for administrator. For administrator password, use administrator API key generated before.
Now we are successfully connected to Queue manager: QM.FOR.YOU.
Expand the connection to see all the queue manager objects.
Remote Administration using REST endpoints
You can also remotely administer the queue manager using admin REST endpoints. For this, you must use administrator id along with administrator API key as the password. In addition, for any modification to the queue manager, an additional HTTP header ibm-mq-rest-csrf-token must be defined with no value.
Get all attributes of a queue manager:
Additional Information
For more information on IBM MQ on Cloud, refer to https://cloud.ibm.com/docs/mqcloud
