[V9.1.0 Jul 2018]

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.

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/v1/. 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 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:

      [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/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!"
  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/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.

What to do next