IBM® MQ v9.0.1 saw the introduction of the REST API for administration. IBM® MQ v9.0.4 introduces a new REST API specifically designed for messaging.

The messaging REST API comes as standard with IBM® MQ v9.0.4, and is enabled by default. You can use the messaging REST API to send and receive IBM® MQ messages in text format.

Applications can issue an HTTP POST to send a message to IBM® MQ, or an HTTP DELETE to destructively get a message 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.

Sending a Message
You can use the HTTP POST method with the following URL resource to put messages to the associated queue manager and queue:

The method puts an IBM® MQ message containing the HTTP request body to the specified queue manager and queue. The method only supports text based HTTP request bodies. Messages are sent as MQSTR formatted messages, and are put using the current user context.

For further information about sending messages with the REST API and the HTTP headers available, see the POST method in the reference section of the KnowledgeCenter.

Receiving a Message
You can use the HTTP DELETE method with the following URL resource to get messages from the associated queue manager and queue.

The method destructively gets 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. Incompatible messages are left on the queue and an appropriate status code returned to the caller.

For further information about receiving messages with the REST API and the HTTP headers available, see the DELETE method in the section of the KnowledgeCenter.

Disabling the Messaging REST API
If required, the messaging REST API can be fully disabled, allowing only the existing administration REST API to be available. This is controlled by the mqweb server property mqRestMessagingEnabled. For more information about enabling or disabling the messaging REST API, see Configuring the messaging REST API.

The following examples show how a typical text message can be sent and received 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.

POST Request:
curl -X POST --header 'Content-Type: text/plain; charset=utf-8' --header 'Accept: text/plain' --header 'ibm-mq-rest-csrf-token: <your-csrf-token>' --header 'ibm-mq-md-expiry: unlimited' --header 'ibm-mq-md-replyTo: REPLYQ' --header 'ibm-mq-md-persistence: nonPersistent' -d 'this is a text message' 'https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/xa/queue/TESTQ/message'

POST Response:
Status: 201
Body: {no response body}
"Cache-Control": "no-cache, no-store, must-revalidate",
"Content-Language": "en-GB",
"Content-Length": "0",
"Content-Security-Policy": "default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-rc 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'",
"Content-Type": "text/plain; charset=utf-8",
"Date": "Mon, 18 Dec 2017 10:27:08 GMT",
"X-Content-Type-Options": "nosniff",
"X-Powered-By": "Servlet/3.1",
"X-XSS-Protection": "1;mode=block",
"ibm-mq-md-messageId": "414d512078612020202020202020202011ac0d5a237ff802"

DELETE Request:
curl -X DELETE --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'

DELETE Response:
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": "Mon, 18 Dec 2017 10:28:06 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": "414d512078612020202020202020202011ac0d5a237ff802",
"ibm-mq-md-persistence": "nonPersistent",
"ibm-mq-md-replyTo": "REPLYQ@xa"

8 comments on"Messaging REST API"

  1. Clément Legouest August 01, 2019

    What about the GET request example ?

  2. I would really like to use this functionality, but our sending app does not put a format of type Format : ‘MQSTR ‘ so we get error
    MQWB0309E: The received message type is unsupported by the mqweb server. Is there anyway to configure the rest server to read messages, that have a ” format?

    • Hi, The messaging REST API only supports text-based message formats which is indicated by the presence of the MQSTR value. A blank format field is therefore intrepreted as an unsupported type which cannot be currently processed by the REST API. Thanks for your query and I hope that clarifies the API’s use.

      Regards, Andy.

  3. how this would handle data if it message body had CRLF in it.

  4. Do you have any sample clients available that use this? Ideally we’d like to see a sample node.js client and a sample java spring framework client. This would make a great developerworks article. Thanks!

  5. hello,

    will be messaging API introduced in the MQ 9 LTS in subsequent patches or for the LTS rather I would need to wait for MQ 10?


    • Hi,

      Thanks for your question regarding the availability of the new messaging REST API. The function was introduced in the v9.0.4 CD release and will therefore be available in the forthcoming LTS release.There are no plans to back-port the function to previous LTS releases. I hope this helps to clarify the functions availability.

      Thanks, Andy.

Join The Discussion

Your email address will not be published.