Using the administrative REST API

When you 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 you use the administrative REST API:

You must authenticate with the mqweb server in order to use the administrative 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 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.

About this task

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

Construct the URL:
1. Determine the prefix URL by entering the following command:
```
dspmqweb status
```
  The URL that you want to use includes the /ibmmq/rest/ phrase.
2. Add the resource to the URL path.
  The following IBM MQ resources are available:
  The following Managed File Transfer resources are available:
  For example, to interact with queue managers, add /qmgr to the prefix URL to create the following URL:
```
https://localhost:9443/ibmmq/rest/v2/admin/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:
```
https://localhost:9443/ibmmq/rest/v2/admin/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:
```
https://localhost:9443/ibmmq/rest/v2/admin/qmgr/QM1?attributes=*
```
5. Add further optional query parameters to the URL.
  
  Add an ampersand, &, to the URL, and then repeat step d.
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.