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 starting

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 we need cURL installed on the system.
The examples use a queue manager QM1. Either create a queue manager with the same name, or substitute an existing queue manager on the system. The queue manager must be on the same machine as the mqweb server.
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

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 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.
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 mqsc resource of the administrative REST API, authenticating as the mqadmin user:
```
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\": \"MSGQ\"}"
```
- Use MQSC commands:
  On z/OS, use a 2CR source instead of the runmqsc command. For more information, see Sources from which we can issue MQSC commands on 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/v2/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/v2/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. 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 messaging REST API and constructing URLs with query parameters: Use the messaging REST API.
When we use the messaging REST API, connections to the queue manager are pooled to optimize performance. We can configure the maximum pool size, and what action is taken when all the connections in the pool are in use: Configure 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.

Parent topic: Messaging using the REST API