Getting started with the administrative REST API

Get started quickly with the administrative REST API and try out a few example requests by using cURL to create, update, view, and delete a queue.

Before you begin

To get you started with using the administrative REST API, 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 you need cURL installed on your system.
  • To complete this task, you must be a user with certain privileges so that you can use the dspmqweb command:
    • [z/OS]On z/OS®, you must have authority to run the dspmqweb command, and write access to the mqwebuser.xml file.
    • [UNIX, Linux, Windows, IBM i]On all other operating systems, you must be a privileged user.

    [IBM i]On IBM® i, the commands should be running in QSHELL.

Procedure

  1. Ensure that you configured the mqweb server for use by the administrative REST API, the administrative REST API for MFT, the messaging REST API, or IBM MQ Console.
    For more information about configuring the mqweb server with a basic registry, see Basic configuration for the mqweb server.
  2. [z/OS] On z/OS, set the WLP_USER_DIR environment variable so that you 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 Creating 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/v2/. 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 your 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\", \"command\": \"define\", \"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