[V9.1.0 Jul 2018]

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 queue manager must be on the same machine as the mqweb server. 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/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message

Note: If you are using a version of IBM® MQ earlier than IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, you must substitute v1 where the URL uses v2. For example, the first part of the URL is as follows: https://host:port/ibmmq/rest/v1/
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.
The queue manager name is case-sensitive.
If the queue manager name includes a forward slash, a period, or a percent sign, these characters must be URL encoded:
  • A forward slash (/) must be encoded as %2F.
  • A percent sign (%) must be encoded as %25.
queueName
Specifies the name of the queue from which to get the next message.
The queue must be defined as being local or an alias pointing to a local queue.
The queue name is case sensitive.
If the queue name includes a forward slash or a percent sign, these characters must be URL encoded:
  • A forward slash, /, must be encoded as %2F.
  • A percent sign, %, must be encoded as %25.

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.
hexValue
The query parameter must be specified as a 48 character hexadecimal encoded string, representing 24 bytes.
For example:

../message?correlationId=414d5120514d4144455620202020202067d8bf5923582e02
messageId=hexValue
Specifies that the HTTP method returns the next message with the corresponding message ID.
hexValue
The query parameter must be specified as a 48 character hexadecimal encoded string, representing 24 bytes.
For example:

../message?messageId=414d5120514d4144455620202020202067d8ce5923582f07
wait=integerValue
Specifies that the HTTP method will wait integerValue milliseconds for the next message to become available.
integerValue
The query parameter must be specified as an integer value representing the millisecond duration. The maximum value is 2147483647.
For example:
../message?wait=120000

Request headers

The following headers must be sent with the request:
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 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 get messages from the specified queue:
  • The queue that is specified by the {queueName} portion of the resource URL, must be GET enabled.
  • [UNIX, Linux, Windows][MQ Appliance]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.
  • [z/OS]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.

[UNIX, Linux, Windows]On UNIX, Linux®, and Windows, you 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).

[z/OS]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.
For example, an invalid query parameter value was specified.
401
Not authenticated.
The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. The ibm-mq-rest-csrf-token header must also be specified. For more information, see Security requirements.
403
Not authorized.
The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal does not have access to all, or a subset of the required IBM MQ resources, or is not in the MQWebUser role. For more information about the access that is required, see Security requirements.
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.
For example, the received message has an incorrect type, or has the correct type but the body could not be processed.
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.
For example:
ibm-mq-md-correlationId: 414d5120514d4144455620202020202067d8bf5923582e02
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.
For example:

ibm-mq-md-messageId: 414d5120514d4144455620202020202067d8ce5923582f07
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.
For example:

ibm-mq-md-replyTo: myReplyQueue@myReplyQMgr

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. Subsequently, all messages are received under sync-point and any unhandled messages are left on the queue. The IBM MQ queue can be configured to move these poison messages to an alternate destination. For further information, see Handling poison messages in IBM MQ classes for JMS.

Examples

The following examples use the v2 resource URL. If you are using a version of IBM MQ earlier than IBM MQ 9.1.5 you 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 removes 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 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 queue Q1 on queue manager QM1: 
    curl -k "https://localhost:9443/ibmmq/rest/v2/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 queue Q1 on queue manager QM1, 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/v2/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"