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:
    • [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 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
  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. 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:

      [z/OS]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.

      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
  5. 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:
    • [z/OS]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)
    • [UNIX, Linux, Windows, IBM i]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
  6. 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!"
  7. 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