GET
We can use the HTTP GET method with the /messaging/qmgr/{qmgrName}/queue/{queueName}/message resource to browse messages from the associated queue manager and queue.
Browses the first available message from the specified queue manager and queue. The queue manager must be on the same machine as the mqweb server. The message body is returned in the HTTP response body. The message must have a format of MQSTR and is received using the current user context.
All messages are left on the queue and an appropriate status code is returned to the caller for any inappropriate messages. For example, a message which does not have a MQSTR format.
- Resource URL
- Optional query parameters
- Request headers
- Request body format
- Security requirements
- Response status codes
- Response headers
- Response body format
- Examples
Resource URL
https://host:port/ibmmq/rest/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message
- qmgrName
- Specifies the name of the queue manager to connect to for messaging. The queue manager must be on the same machine as the mqweb server.
- queueName
- Specifies the name of the queue from which to browse the message.
We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.
Optional query parameters
- correlationId=hexValue
- Specifies that the HTTP method returns the next message with the corresponding correlation ID.
- messageId=hexValue
- Specifies that the HTTP method returns the next message with the corresponding message ID.
Request headers
The following headers must be sent with the request:
- Authorization
- This header must be sent if we are using basic authentication. For more information, see Use HTTP basic authentication with the REST API.
- ibm-mq-rest-csrf-token
- This header must be set, but the value can be anything, including being blank.
The following headers can optionally be sent with the request:
- Accept-Charset
- This header can be used to indicate what character set is acceptable for the response. If specified, this header must be set as UTF-8.
- Accept-Language
- This header specifies the required language for any exceptions or error messages returned in the response message body.
Request body format
None.
Security requirements
The caller must be authenticated to the mqweb server. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API. For more information about security for the REST API, see IBM MQ Console and REST API security.
Once authenticated to the mqweb server the user is capable of using both the messaging REST API and the administrative REST API.
The security principal of the caller must be granted the ability to browse messages from the specified queue:- The queue that is specified by the {queueName} portion of the resource URL, must be BROWSE enabled.
For the queue that is specified by the {queueName}
portion of the resource URL, +GET, +INQ, and
+BROWSE authority must be granted to the security principal of the caller.
For the queue that is specified by the {queueName} portion of
the resource URL, UPDATE, access must be granted to the security principal of the
caller.
On UNIX, Linux, and Windows, we can
grant authority to security principals to use IBM MQ
resources by using the setmqaut command. For more information, see setmqaut (grant or
revoke authority).
On z/OS, see Set up security on z/OS.
Response status codes
- 200
- Message received successfully.
- 204
- No message available.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Queue does not exist.
- 500
- Server issue or error code from IBM MQ.
- 501
- The HTTP response could not be constructed.
- 502
- The current security principal cannot receive the message as the messaging provider does not support the required function. For example, if the mqweb server class path is invalid.
- 503
- Queue manager not running.
Response headers
The following headers are returned with the response:
- Content-Language
- Specifies the language identifier of the response message in the event of any errors or exceptions. Used in conjunction with Accept-Language request header to indicate the required language for any error or exception conditions. The mqweb server default is used if the requested language is unsupported.
- Content-Length
- Specifies the length of the HTTP response body, even when there is no content. The value contains the length (bytes) of the message data.
- Content-Type
- Specifies the type of content returned in the response body of the received message. Upon success the value is text/plain;charset=utf-8. In the event of any errors or exceptions, the value is application/json;charset=utf-8.
- ibm-mq-md-correlationId
- Specifies the correlation ID of the received message. The header is returned if the received message contains a valid correlation ID. It is represented as a 48 character hexadecimal encoded string, representing 24 bytes.
- ibm-mq-md-expiry
- Specifies the remaining expiry duration of the received message. The header can be one of the
following values:
- unlimited
- The message does not expire.
- Integer value
- Remaining milliseconds before message expiry.
- ibm-mq-md-messageId
- Specifies the message ID that is allocated by IBM MQ to this message. Like the ibm-mq-md-correlationId header, it is represented as a 48 character hexadecimal encoded string, representing 24 bytes.
- ibm-mq-md-persistence
- Specifies the persistence of the received message. The header can be one of the following values:
- nonPersistent
- The message does not survive system failures or queue manager restarts.
- persistent
- The message survives system failures or queue manager restarts.
- ibm-mq-md-replyTo
- Specifies the reply-to destination for the received message. The format of the header uses the standard notation of the reply-to queue and queue manager, replyQueue@replyQmgr.
Response body format
Upon success, the response body contains the message body from the received message. If an error occurs, the response body contains a JSON formatted error message. Both responses are UTF-8 encoded. For more information, see REST API error handling.
Be aware that when receiving a message only IBM MQ MQSTR formatted messages are supported.
Browsing a queue that has been marked as GET inhibited returns no content.
If the queue that is being browsed contains messages with duplicate message identifiers, the first message is returned when filtering on the message identifier.
Examples
The following examples use the v2 resource URL. If you are using a version of IBM MQ earlier than Version 9.1.5 we must use the v1 resource URL instead. That is, in the resource URL, substitute v1 where the example URL uses v2.
The following example logs in a user called mquser with the password mquser. In cURL, the log in request might look like the following Windows example. The LTPA token is stored in the cookiejar.txt file by using the -c flag:curl -k "https://localhost:9443/ibmmq/rest/v2/login" -X POST
-H "Content-Type: application/json" --data "{\"username\":\"mquser\",\"password\":\"mquser\"}"
-c c:\cookiejar.txt
After the user is logged in, the LTPA token and ibm-mq-rest-csrf-token HTTP header are used to authenticate further requests. The ibm-mq-rest-csrf-token token_value can be any value, including blank.
- The following Windows cURL example browses the next
available message from queue Q1 on queue manager QM1, using
default options:
curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message" -X GET -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" -H "Accept: text/plain"
- The following Windows cURL example browses a message
with a specific correlation ID, 0000000000000000000000000000000000000000abcdabcd,
from queue Q1 on queue manager QM1:
curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message?correlationId=0000000000000000000000000000000000000000abcdabcd" -X GET -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" -H "Accept: text/plain"
Parent topic: /messaging/qmgr/{qmgrName}/queue/{queueName}/message