GET

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 browse the message.

The queue must be defined as being local or an alias that points 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.

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

correlationId=ID:hexValue or correlationId=application_specific_value

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, and preceded by the string "ID:".

For example:

../message?correlationId=ID:414d5120514d4144455620202020202067d8bf5923582e02

application_specific_value

The query parameter can be specified as an application-specific string.

For example:

../message?correlationId=My-Custom-CorrelId

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

messageId=ID: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, and preceded by the string "ID:".

For example:

../message?messageId=ID:414d5120514d4144455620202020202067d8ce5923582f07

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.

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.

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.

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.

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-correlationId

Specifies the correlation ID of the received message. The header is returned if the received message contains a valid correlation ID. The correlation ID can take one of the following forms:

• A 48 character hexadecimal encoded string, representing 24 bytes, prefixed with the string "ID:". For example:

  ibm-mq-md-correlationId: ID:414d5120514d4144455620202020202067d8bf5923582e02

• An application-specific value. The value is an application-specific string:

  ibm-mq-md-correlationId: My-Custom-CorrelId

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-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, prefixed with the string "ID:"

For example:

ibm-mq-md-messageId: ID: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-priority

Returns the setting of the message priority. For example:

ibm-mq-md-priority: 3

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

ibm-mq-usr

Returns message user-defined properties. Multiple properties can be set on a message, in which case there will be two or more separate instances of the ibm-mq-usr response header.

For example:

ibm-mq-usr: myIProp;5;short
ibm-mq-usr: mySProp;”hi”;string
ibm-mq-usr: myBProp;true;boolean

The properties have the following syntax:

ibm-mq-usr: property_name; user_value; user_type

property_name

The name of the user property being specified. This must be a valid JMS property name.

user_value

The value of the property.

user_type

The type of the property:

• boolean (true/false, MQBOOL)
• byte (8-bit integer, MQINT8)
• short (16-bit integer, MQINT16)
• integer (32-bit integer, MQINT32)
• long (64-bit integer, MQINT64)
• float (32-bit real, MQFLOAT32)
• double (64-bit real, MQFLOAT64)
• string (quoted string)

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

• 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"

• 

  The following Windows cURL example is the same as the previous example, but uses REST API V3. The example lists only those messages with the corresponding correlation ID, 0000000000000000000000000000000000000000abcdabcd, from queue Q1 on queue manager QM1:

  curl -k "https://localhost:9443/ibmmq/rest/v3/messaging/qmgr/QM1/queue/Q1/message?correlationId=ID:0000000000000000000000000000000000000000abcdabcd" 
  -X GET -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" 
  -H "Accept: text/plain"