Using the messaging REST API

When you 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 you begin

Consider these things before you use the messaging REST API:

You must authenticate with the mqweb server in order to use the messaging REST API. You 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/v1/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, you must use the appropriate URL encoding:
- A forward slash, /, must be encoded as %2F.
- A percent sign, %, must be encoded as %25.

About this task

When you 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, you can send the HTTP request to IBM MQ. You can send the request by using the HTTP implementation that is built into the programming language of your choice. You can also send the request by using command line tools such as cURL, or a web browser, or web browser add-on.

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

Procedure

Construct the URL:
1. Start with the following prefix URL:
```
https://host:port/ibmmq/rest/v1/messaging
```
  host
  
  Specifies the host name or IP address that the messaging REST API is available on.
  
  The default value is localhost.
  
  port
  
  Specifies the HTTPS port number that the messaging REST API uses.
  
  The default value is 9443.
  
  If you enable HTTP connections, you can use HTTP instead of HTTPS. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.
  
  For more information about how to determine the prefix URL, see Determining the REST API URL.
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/v1/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/v1/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.
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 your chosen programming language.
- Use a tool such as a REST client browser add-on or cURL.