Messaging using the REST API

We can use the messaging REST API to perform simple point-to-point and publish messaging. We can publish messages to a topic, send messages to a queue, browse messages on a queue, and destructively get messages from a queue. Information is sent to, and received from, the messaging REST API in plain text format.


Before starting

Note:

  • The messaging REST API is enabled by default. We can disable the messaging REST API to prevent all messaging. For more information about enabling or disabling the messaging REST API, see Configuring the messaging REST API.
  • The messaging REST API is integrated with IBM MQ security. To use the messaging REST API, users must be authenticated to the mqweb server and must be a member of the MQWebUser role. The user must also be authorized to access the specified queueor topic. For more information about security for the REST API, see IBM MQ Console and REST API security.
  • If we use Advanced Message Security (AMS) with the messaging REST API, note that all messages are encrypted by using the context of the mqweb server, not the context of the user that posts the message.
  • 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.
  • The messaging REST API does not give you once-and-once only delivery of messages with transactional support. If an HTTP POST is issued and the connection fails before an HTTP response is received by the client, the client can not immediately tell if the message was sent to the specified queue, or published to the specified topic. If an HTTP DELETE is issued and the connection fails before an HTTP response is received by the client, then a message might have been destructively got from the queue and lost, as there is no way of rolling the destructive get back.
  • Newlines in incoming strings are removed by the HTTP POST operation. REST applications should not use newlines in messages that are sent or published using the REST API, as they will be lost.

  • Getting started with the messaging REST API
    Get started quickly with the messaging REST API and try out a few example commands by using cURL.
  • 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.
  • REST API error handling
    The REST API reports errors by returning an appropriate HTTP response code, for example 404 (Not Found), and a JSON response.
  • REST API discovery
    Documentation for the REST API is available within the IBM Knowledge Center and in Swagger format. Swagger is a commonly used approach for documenting REST APIs. The Swagger documentation for the REST API can be viewed by enabling the API discovery feature.
  • REST API national language support
    The REST API supports, with certain qualifications, the ability to specify national languages as part of an HTTP request.

Parent topic: Developing REST applications with IBM MQ


Related information