DELETE
You can use the HTTP DELETE method with the /messaging/qmgr/{qmgrName}/queue/{queueName}/message
resource to get messages from the associated queue manager and queue.
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 example,
a message which does not have a MQSTR
format.
Resource URL
https://host:port/ibmmq/rest/v1/messaging/qmgr/{qmgrName}/queue/{queueName}/message
- qmgrName
- Specifies the name of the queue manager to connect to for messaging.
- queueName
- Specifies the name of the queue from which to get the next message.
You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring 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.
- wait=integerValue
- Specifies that the HTTP method will wait integerValue milliseconds for the next message to become available.
Request headers
- Authorization
- This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.
- ibm-mq-rest-csrf-token
- This header must be sent with a value that is the content of the
csrfToken
cookie. The content of thecsrfToken
cookie is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.
- 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.
- 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. - The queue that is specified by the {queueName} portion of the resource
URL, must be
GET
enabled.
On UNIX, Linux®, and Windows, you can grant authority to security principals to use IBM MQ resources by using the mqsetaut command. For more information, see mqsetaut.
On z/OS®, see Setting 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.
- 405
- Queue is GET inhibited.
- 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
- 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 isapplication/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.
Examples
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/v1/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.
token-value
is the value of the
csrfToken
cookie, and from IBM MQ 9.0.5
token-value
is any value, including blank.- The following Windows cURL example removes the next
available message from queue
Q1
on queue managerQM1
, using default options:curl -k "https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/Q1/message" -X DELETE -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" -H "Accept: text/plain"
- The following Windows cURL example removes a message
with a specific correlation ID,
0000000000000000000000000000000000000000abcdabcd
, from queueQ1
on queue managerQM1
:curl -k "https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/Q1/message?correlationId=0000000000000000000000000000000000000000abcdabcd" -X DELETE -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" -H "Accept: text/plain"
- The following Windows cURL example removes a message
with a specific correlation ID,
0000000000000000000000000000000000000000abcdabcd
, from queueQ1
on queue managerQM1
, waiting for up to 30 seconds for the message to become available. If 30 seconds passes without the specified message being put to the queue, the DELETE call returns without a message:curl -k "https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/Q1/message?correlationId=0000000000000000000000000000000000000000abcdabcd&wait=30000" -X DELETE -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" -H "Accept: text/plain"