Get started quickly with the messaging REST API
and try out a few example commands by using cURL.
Before you begin
To get you started with using the messaging REST API, the examples in this task have the following
requirements:
- The examples use cURL to send REST requests to put and get messages from a queue. Therefore, to
complete this task you need cURL installed on your system.
- The examples use a queue manager
QM1
. Either create a queue manager with the
same name, or substitute an existing queue manager on your system. The queue manager must be on the
same machine as the mqweb server.
-
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
-
Ensure that the mqweb server is configured for the messaging REST API:
- 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.For more information about creating a basic configuration for the mqweb server with a basic registry, see Basic configuration for the mqweb server.
- If the mqweb server is already configured, ensure that you added the appropriate users to
enable messaging in step 5 of
-
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.
- Create a queue,
MSGQ
, on queue manager QM1
. This queue
is used for messaging. Use one of the following methods:
- Use a POST request on the
queue
resource of the administrative REST API, authenticating as the mqadmin
user:
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST -u mqadmin:mqadmin -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" --data "{\"name\":\"MSGQ\"}"
- Use MQSC commands:
On z/OS,
use a 2CR source instead of the runmqsc command. For more information, see Sources from which you can issue MQSC commands on z/OS.
- Start runmqsc for the queue manager by entering the following
command:
runmqsc QM1
- Use the DEFINE QLOCAL MQSC command to create the
queue:
DEFINE QLOCAL(MSGQ)
- Exit runmqsc by entering the following
command:
end
- Grant authority for the user that you added to the mqwebuser.xml in
step 5 of Basic configuration for the
mqweb server to access the queue
MSGQ
. Substitute your user where
myuser
is used:
- On z/OS:
- Grant your user access to the
queue:
RDEFINE MQQUEUE hlq.MSGQ UACC(NONE)
PERMIT hlq.MSGQ CLASS(MQQUEUE) ID(MYUSER) ACCESS(UPDATE)
- Grant the mqweb started task user ID access to set all context on the
queue:
RDEFINE MQADMIN hlq.CONTEXT.MSGQ UACC(NONE)
PERMIT hlq.CONTEXT.MSGQ CLASS(MQADMIN) ID(mqwebStartedTaskID) ACCESS(CONTROL)
- On all other operating systems, if your user is in the mqm group, authority
is already granted. Otherwise, enter the following commands:
- Start runmqsc for the queue manager by entering the following
command:
runmqsc QM1
- Use the SET AUTHREC MQSC command to give your user browse, inquire, get and
put authorities on the
queue:
SET AUTHREC PROFILE(MSGQ) OBJTYPE(QUEUE) +
PRINCIPAL(myuser) AUTHADD(BROWSE, INQ, GET, PUT)
- Exit runmqsc by entering the following
command:
end
- Put a message with the content
Hello World!
on the queue
MSGQ
on queue manager QM1
, by using a POST request on the
message
resource. Substitute your user ID and password from the
mqwebuser.xml for myuser
and
mypassword
:
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/messaging/qmgr/QM1/queue/MSGQ/message -X POST -u myuser:mypassword -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: text/plain;charset=utf-8" --data "Hello World!"
- Destructively get the message from queue
Hello World!
on the queue
MSGQ
on queue manager QM1
, by using a DELETE request on the
message
resource. Substitute your user ID and password from the
mqwebuser.xml for myuser
and
mypassword
:
curl -k https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/QM1/queue/MSGQ/message -X DELETE -u myuser:mypassword -H "ibm-mq-rest-csrf-token: value"
The message Hello World!
is returned.