Getting started with the messaging REST API

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:
- 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.
- If the mqweb server is already configured, ensure that you added the appropriate users to enable messaging in step 5 of Basic configuration for the mqweb server.
  - If mqRestMessagingAdoptWebUserContext is set to true in the mqweb server configuration, users of the messaging REST API must be a member of the MQWebUser role. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API. The users must also be authorized to access queues and topics that are used for messaging through OAM or RACF®.
  - If mqRestMessagingAdoptWebUserContext is set to false in the mqweb server configuration, the user ID that is used to start the mqweb server must be authorized to access queues used for messaging through OAM or RACF.
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/v3/. 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 mqsc resource of the administrative REST API, authenticating as the mqadmin user:
```
curl -k https://localhost:9443/ibmmq/rest/v3/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\": \"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 and PCF commands on IBM MQ for z/OS.
  1. Start runmqsc for the queue manager by entering the following command:
```
runmqsc QM1
```
  2. Use the DEFINE QLOCAL MQSC command to create the queue:
```
DEFINE QLOCAL(MSGQ)
```
  3. 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:
  1. Grant your user access to the queue:
```
RDEFINE MQQUEUE hlq.MSGQ UACC(NONE)
PERMIT hlq.MSGQ CLASS(MQQUEUE) ID(MYUSER) ACCESS(UPDATE)
```
  2. 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:
  1. Start runmqsc for the queue manager by entering the following command:
```
runmqsc QM1
```
  2. 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)
```
  3. 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/v3/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/v3/messaging/qmgr/QM1/queue/MSGQ/message -X DELETE -u myuser:mypassword -H "ibm-mq-rest-csrf-token: value"
```
The message Hello World! is returned.

What to do next

The examples use basic authentication to secure the request. You can use token-based authentication or client-based authentication instead. For more information, see Using client certificate authentication with the REST API and IBM MQ Console, and Using token-based authentication with the REST API.
Learn more about using the messaging REST API and constructing URLs with query parameters: Using the messaging REST API.
When you use the messaging REST API, connections to the queue manager are pooled to optimize performance. You can configure the maximum pool size, and what action is taken when all the connections in the pool are in use: Configuring the messaging REST API.
Browse the reference information for the available messaging REST API resources and all the available query parameters: messaging REST API reference.
Discover the administrative REST API, a RESTful interface for IBM MQ administration: Administration using the REST API.
Discover the IBM MQ Console, a browser-based GUI: Administration using the IBM MQ Console.