+

Search Tips | Advanced Search

Use the messaging REST API

When we use the messaging REST API, you invoke HTTP methods on URLs to send and receive IBM MQ messages. The HTTP method, for example POST, represents the type of action to be performed on the object that is represented by the URL. Further information about the action might be encoded in query parameters. Information about the result of performing the action might be returned as the body of the HTTP response.


Before starting

Consider these things before we use the messaging REST API:

  • We must authenticate with the mqweb server in order to use the messaging REST API. We can authenticate by using HTTP basic authentication, client certificate authentication, or token based authentication. For more information about how to use these authentication methods, see IBM MQ Console and REST API security.
  • The REST API is case-sensitive. For example, an HTTP POST on the following URL results in an error if the queue manager is called qmgr1. 
    /ibmmq/rest/v2/messaging/qmgr/QMGR1/queue/Q1/message
  • Not all of the characters that can be used in IBM MQ object names can be directly encoded in a URL. To encode these characters correctly, we must use the appropriate URL encoding:

    • A forward slash must be encoded as %2F.
    • A percent sign must be encoded as %25.
    • A period must be encoded as %2E.
    • A question mark must be encoded as %3F.

  • When receiving or browsing a message only IBM MQ MQSTR formatted messages are supported. Subsequently, all messages are destructively 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.


When we use the REST API to perform a messaging action on an IBM MQ queue object, you first need to construct a URL to represent that object. Each URL starts with a prefix, which describes which host name and port to send the request to. The rest of the URL describes a particular object, or route to that object, known as a resource.

The messaging action that is to be performed on the resource defines whether the URL needs query parameters or not. It also defines the HTTP method that is used, and whether additional information is sent to the URL, or returned from it. The additional information might form part of the HTTP request, or be returned as part of the HTTP response.

After you construct the URL, we can send the HTTP request to IBM MQ. We can send the request by using the HTTP implementation that is built into the programming language of our choice. We can also send the request by using command line tools such as cURL, or a web browser, or web browser add-on.

Important: We must, as a minimum, carry out steps 1.a and 1.b.


Procedure

  1. Construct the URL:
    1. Determine the prefix URL by entering the following command: 
      dspmqweb status
      The URL that we want to use includes the /ibmmq/rest/ phrase.
    2. Add the queue and associated queue manager resources to use for messaging to the URL path.

      In the messaging reference, the variable segments can be identified in the URL by the braces that surround it { }. For futher information, see /messaging/qmgr/{qmgrName}/queue/{queueName}/message.

      For example, to interact with queue Q1 associated with queue manager QM1, add /qmgr and /queue to the prefix URL to create the following URL:

      https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message
    3. Optional: Add an optional query parameter to the URL.

      Add a question mark, ?, query parameter, equal sign =, and a value to the URL.

      For example, to wait for a maximum of 30 seconds for the next message to become available, create the following URL:

      https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message?wait=30000
    4. Optional: Add further optional query parameters to the URL.

      Add an ampersand, &, to the URL, and then repeat step 1c.

  2. Invoke the relevant HTTP method on the URL. Specify any optional message payload, and provide the appropriate security credentials to authenticate. For example:

    • Use the HTTP/REST implementation of our chosen programming language.
    • Use a tool such as a REST client browser add-on or cURL.

Parent topic: Messaging using the REST API

Last updated: 2020-10-04