Getting started with the administrative REST API

Before starting

The examples in this task have the following requirements:

• The examples use cURL to make REST requests to display information about queue managers on the system, and to create a queue, update, view, and delete a queue. Therefore, to complete this task we need cURL installed on the system.

• To complete this task, we must be a user with certain privileges so that we can use the dspmqweb command:
  • On z/OS, we must have authority to run the dspmqweb command, and write access to the mqwebuser.xml file.
  • On all other operating systems, we must be a privileged user.

Procedure

1. If the mqweb server is not already configured for use by the administrative REST API, the administrative REST API for MFT, the messaging REST API, or IBM MQ Console, configure the mqweb server with a basic registry.

2. On z/OS, set the WLP_USER_DIR environment variable so that we can use the dspmqweb command. Set the variable to point to your mqweb server configuration by entering the following command:
   export WLP_USER_DIR=WLP_user_directory

   where WLP_user_directory is the name of the directory that is passed to crtmqweb. For example:

   export WLP_USER_DIR=/var/mqm/web/installation1

   For more information, see Create the mqweb server.

3. Determine the REST API URL by entering the following command:
   dspmqweb status

   The examples in the following steps assume that your REST API URL is the default URL https://localhost:9443/ibmmq/rest/v1/. If your URL is different than the default, substitute your URL in the following steps.

4. Try out a GET request on the qmgr resource by using basic authentication with the mqadmin user:
   curl -k https://localhost:9443/ibmmq/rest/v2/admin/qmgr -X GET -u mqadmin:mqadmin

5. Create, display, alter, and delete a queue by using the mqsc resource:

   This example uses a queue manager QM1. Either create a queue manager with the same name, or substitute an existing queue manager on the system.

   1. Make a POST request on the mqsc resource to create the local queue: In the body of the request, the name of the new queue is set to Q1. Basic authentication is used, and an ibm-mq-rest-csrf-token HTTP header with an arbitrary value is set in the cURL REST request. This additional header is required for POST, PATCH, and DELETE requests:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"qualifier\": \"qlocal\", \"name\": \"Q1\"}"

   2. Make a POST request on the mqsc resource to view the local queue created in step 5.a:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"command\": \"display\", \"qualifier\": \"qlocal\", \"name\": \"Q1\"}"

   3. Make a POST request on the mqsc resource to resource to update the description of the queue:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"command\": \"alter\", \"qualifier\": \"qlocal\", \"name\": \"Q1\", \"parameters\": {"\descr\": \"new description\" }}"

   4. Make a POST request on the mqsc resource to view the new queue description. Specify the responseParameters attribute in the request body so that the response includes the description field:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"command\": \"display\", \"qualifier\": \"qlocal\", \"name\": \"Q1\", \"responseParameters\" : [\"descr\"]}"

   5. Make a POST request on the mqsc resource to delete the queue:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"command\": \"delete\", \"qualifier\": \"qlocal\", \"name\": \"Q1\"}"

   6. Make a POST request on the mqsc resource to prove that the queue is deleted:
      curl -k https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"type\": \"runCommandJSON\", \"command\": \"display\", \"qualifier\": \"qlocal\", \"name\": \"Q1\"}"

What to do next

• The examples use basic authentication to secure the request. We can use token-based authentication or client-based authentication instead. For more information, see Use client certificate authentication with the REST API and IBM MQ Console, and Use token-based authentication with the REST API.
• Learn more about using the administrative REST API and constructing URLs with query parameters: Use the administrative REST API.
• Browse the reference information for the available administrative REST API resources and all the available optional query parameters: administrative REST API reference.
• Learn how to use the administrative REST API to administer IBM MQ objects on remote systems: Remote administration using the REST API.
• Learn how to use the administrative REST API with MFT:Getting started with the REST API for MFT.
• Discover the messaging REST API, a RESTful interface for IBM MQ messaging: Messaging using the REST API.
• Discover the IBM MQ Console, a browser-based GUI: Administration using a web console.

• Getting started with the REST API for MFT
  Get started quickly with the administrative REST API for Managed File Transfer and try out a few example requests to view the MFT agent status, and to view a list of transfers.
• 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.

Parent topic: Administration using the REST API