Messaging REST API

 View Only

Messaging REST API 

Wed March 04, 2020 01:18 PM

A.Owen
Published on 19/12/2017 / Updated on 02/08/2018

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:
/messaging/qmgr/{qmgrName}/queue/{queueName}/message

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.
/messaging/qmgr/{qmgrName}/queue/{queueName}/message

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.

Examples
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"
}

Entry Details

Statistics
0 Favorited
24 Views
1 Files
0 Shares
18 Downloads
Attachment(s)
pdf file
Messaging REST API.pdf   107 KB   1 version
Uploaded - Wed March 04, 2020

Tags and Keywords

Related Entries and Links

No Related Resource entered.