A.Owen
Published on 08/08/2019
IBM® MQ v9.0.4 saw the introduction of the REST API for messaging which provided the POST and DELETE methods for sending and receiving messages respectively. IBM® MQ v9.1.3 extends the API to provide GET methods for browsing messages.
You can use the API to send, receive and browse IBM® MQ messages in text format. Applications can issue an HTTP POST to send a message to IBM® MQ, an HTTP DELETE to destructively get a message from IBM® MQ, or an HTTP GET to browse an indivdual message or message list from IBM® MQ.
Support is provided for several different HTTP headers which can be used to set or return common message properties.
For further information, see Messaging using the REST API.
Messaging Security
The messaging REST API is fully integrated with IBM® MQ security. Users must be authenticated to the mqweb server and must be a member of the existing MQWebUser role. The necessary authorizations must also be granted to the destination queues. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API.
Disabling the Messaging REST API
The messaging REST API is enabled by default. For more information about enabling or disabling the messaging REST API, see Configuring the messaging REST API.
Browsing a Message
You can use the HTTP GET method with the following URL resource to browse the next available message which matches any filtering criteria from the associated queue manager and queue.
/messaging/qmgr/{qmgrName}/queue/{queueName}/message
The method browses the next available message from the specified queue manager and queue, returning the message body in the HTTP response body. The message must have a format of MQSTR, and is received using the current user context (i.e. the issuer of the request). Incompatible messages are not browsed and an appropriate status code returned to the caller.
For further information about browsing messages with the REST API and the HTTP headers available, see the GET method in the REST API resources section of the KnowledgeCenter.
Browsing a Message List
You can use the HTTP GET method with the following URL resource to browse a list of available messages which matches any filtering criteria from the associated queue manager and queue.
/messaging/qmgr/{qmgrName}/queue/{queueName}/messagelist
The method returns a summary list of messages from the specified queue manager and queue. The summary data is returned in the HTTP response body as a JSON formatted array. The data does not contain the payload of the messages and is received using the current user context (i.e. the issuer of the request). No messages are removed from the associated queue.
Applications may iterate through the returned JSON array using the previous GET method (/messaging/qmgr/{qmgrName}/queue/{queueName}/message) to browse individual message content filtered by the message and/or correlation ID.
For further information about browsing message lists with the REST API and the HTTP headers available, see the GET method in the REST API resources section of the KnowledgeCenter.
Examples
The following examples show how text messages can be iterated over and browsed via the messaging REST API using CURL. You should insert your own CSRF token and substitute the Queue Manager, Queue, and other options according to your own configuration.
By default, a maximum of ten messages are returned in the message summary list. This can be changed by appending the limit parameter to the URL.
GET Request (message list):
curl -X GET --header 'Accept: application/JSON' --header 'ibm-mq-rest-csrf-token: <your-csrf-token>' 'https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/xa/queue/TESTQ/messagelist?limit=100'
GET Response (message list):
Status: 200
Body: {"messages":[{"format":"MQSTR","messageId":"414d5120514d41444556202020202020f8b14a5d250fc902","correlationId":"414d5120514d41444556202020202020e993d45a2228c402"},{"format":"MQSTR","messageId":"414d5120514d41444556202020202020f8b14a5d250fc903","correlationId":"414d5120514d41444556202020202020e993d45a2228c403"},{"format":"MQSTR","messageId":"414d5120514d41444556202020202020f8b14a5d250fc904","correlationId":"414d5120514d41444556202020202020e993d45a2228c404"}]}
{
"Cache-Control": "no-cache, no-store, must-revalidate",
"Content-Language": "en-GB",
"Content-Length": "394",
"Content-Security-Policy": "default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'",
"Content-Type": "application/json; charset=utf-8",
"Date": "Wed, 07 Aug 2019 11:57:29 GMT",
"X-Content-Type-Options": "nosniff",
"X-Powered-By": "Servlet/3.1",
"X-XSS-Protection": "1;mode=block",
"ibm-mq-total-browse-size": "3"
}
The ibm-mq-total-browse-size response header can be used to determine whether the returned summary data contains all available messages. An application can subsequently iterate over the JSON array providing the required filtering parameters.
GET Request (message):
curl -X GET --header 'Accept: text/plain' --header 'ibm-mq-rest-csrf-token: <your-csrf-token>' 'https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/xa/queue/TESTQ/message?messageId=414d5120514d41444556202020202020f8b14a5d250fc903'
GET Response (message):
Status: 200
Body: this is a text message
{
"Cache-Control": "no-cache, no-store, must-revalidate",
"Content-Language": "en-GB",
"Content-Length": "22",
"Content-Security-Policy": "default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'",
"Content-Type": "text/plain; charset=utf-8",
"Date": "Wed, 07 Aug 2019 12:10:18 GMT",
"X-Content-Type-Options": "nosniff",
"X-Powered-By": "Servlet/3.1",
"X-XSS-Protection": "1;mode=block",
"ibm-mq-md-expiry": "unlimited",
"ibm-mq-md-messageId": "414d5120514d41444556202020202020f8b14a5d250fc903",
"ibm-mq-md-persistence": "nonPersistent",
"ibm-mq-md-replyTo": "REPLYQ@xa"
}