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:
- On z/OS®, you must have authority
to run the dspmqweb command, and write access to the
mqwebuser.xml file.
- On all other operating systems, you must be a privileged user.
On IBM® i, the commands should be running in
QSHELL.
Procedure
-
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.
-
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.
-
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.
- Try out a GET request on the
qmgr
resource by using basic authentication
with the mqadmin
user:
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr -X GET -u mqadmin:mqadmin
- 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.
- 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/v1/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\"}"
- 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/v1/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\"}"
- Make a POST request on the
mqsc
resource to resource to update the
description of the queue:
curl -k https://localhost:9443/ibmmq/rest/v1/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\" }}"
- 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/v1/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\"]}"
- Make a POST request on the
mqsc
resource to delete the queue:
curl -k https://localhost:9443/ibmmq/rest/v1/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\"}"
- Make a POST request on the
mqsc
resource to prove that the queue is
deleted:
curl -k https://localhost:9443/ibmmq/rest/v1/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\"}"