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
- 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
.
- A forward slash, /, must be encoded as
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.