Use the administrative REST API

When we use the administrative REST API, you invoke HTTP methods on URLs that represent the various IBM MQ objects, such as queue managers or queues. 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 provided in JSON as part of the payload of the HTTP method, or 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 we use the administrative REST API:

• You must authenticate with the mqweb server in order to use the administrative 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 GET on the following URL does not display information if the queue manager is called qmgr1.

  /ibmmq/rest/v1/admin/qmgr/QMGR1

• 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.
• Due to the behavior of some browsers, do not name objects by using only period or forward slash characters.

When we use the REST API to perform an action on an 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 set of objects, known as a resource.

The 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, in JSON form. The additional information might form part of the HTTP request, or be returned as part of the HTTP response.

After you construct the URL, and create an optional JSON payload for sending in the HTTP request, 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 your choice. We can also send the requests 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

1. Construct the URL:
   1. Start with the following prefix URL: Version 9.0.4 and later:

      https://host:port/ibmmq/rest/v1/admin

      Version 9.0.3 and earlier:

      https://host:port/ibmmq/rest/v1

      host

      Specifies the host name or IP address that the administrative REST API is available on.

      The default value is localhost.

      port

      Specifies the HTTPS port number that the administrative REST API uses.

      The default value is 9443.

      If you enable HTTP connections, we can use HTTP instead of HTTPS. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.

      For more information about how to determine the prefix URL, see Determining the REST API URL.

   2. Add the resource to the URL path. The following resources are available:
      • installation
      • qmgr
      • queue
      • subscription
      • channel

      For example, to interact with queue managers, add /qmgr to the prefix URL to create the following URL:

      Version 9.0.4 and later:

      https://localhost:9443/ibmmq/rest/v1/admin/qmgr

      Version 9.0.3 and earlier:

      https://localhost:9443/ibmmq/rest/v1/qmgr

   3. Optional: Add any additional optional path segments to the URL.

      In the reference information for each object type, the optional segments can be identified in the URL by the braces that surround it { }.

      For example, add the queue manager name QM1 to the URL to create the following URL:

      Version 9.0.4 and later:

      https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1

      Version 9.0.3 and earlier:

      https://localhost:9443/ibmmq/rest/v1/qmgr/QM1

   4. Optional: Add an optional query parameter to the URL.

      Add a question mark, ?, variable name, equal sign =, and a value or list of values to the URL.

      For example, to request all attributes of queue manager QM1, create the following URL:

      Version 9.0.4 and later:

      https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1?attributes=*

      Version 9.0.3 and earlier:

      https://localhost:9443/ibmmq/rest/v1/qmgr/QM1?attributes=*

   5. Add further optional query parameters to the URL.

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

2. Invoke the relevant HTTP method on the URL. Specify any optional JSON 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.