Getting started with the administrative REST API

Before you can start the administrative REST API you must install the correct components, enable the REST API, configure security, and start the mqweb server.

Before you begin

[IBM i] On IBM® i, the commands should be running in QSHELL.

About this task

The procedure for this task focuses on getting started quickly with the administrative REST API. The steps for configuring security outline how to set up a basic user registry, but other options for configuring users and roles exist. For more information about configuring security for the administrative REST API, see IBM MQ Console and REST API security.

Note: You must be a privileged user to access the mqwebuser.xml file.

Procedure

Install the IBM MQ Console and REST API component:
- On AIX®,install the mqm.web.rte fileset.
- On Linux®, install the MQSeriesWeb component. For more information about installing components and features on Linux, see Linux installation tasks.
- On Windows, install the Web Administration feature. For more information about installing components and features on Windows, see Windows installation tasks.
- On z/OS®, install the IBM MQ for z/OS Unix System Services Web Components feature. For more information about installing components and features on z/OS, see z/OS installation tasks.
Optional: From IBM MQ 9.0.2, the administrative REST API is enabled by default. However, in IBM MQ 9.0.1, the administrative REST API is disabled by default. If you are using IBM MQ 9.0.1, enable the REST API by adding the following XML to the mqwebuser.xml file, within the <server> tags:
<variable name="mqRestAutostart" value="true"/>
The mqwebuser.xml can be found in one of the following directories:
- MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb
- WLP_user_directory/servers/mqweb
  where WLP_user_directory is the directory that was specified when the crtmqweb.sh script ran to create the mqweb server definition.
From IBM MQ 9.0.2, security is enabled for the administrative REST API. You must configure users and roles before you can use the administrative REST API:
1. Copy the basic_registry.xml file from the MQ_INSTALLATION_PATH/web/mq/samp/configuration directory.
2. Place the sample XML file in the appropriate directory:
  - On UNIX, Linux, and Windows: MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb
  - On z/OS: WLP_user_directory/servers/mqweb
    where WLP_user_directory is the directory that was specified when the crtmqweb.sh script ran to create the mqweb server definition.
3. Rename the sample XML file to mqwebuser.xml.
  
  Note: This renamed file replaces an existing file that is also used for the IBM MQ Console. Therefore, if you changed the mqwebuser.xml file for the IBM MQ Console, copy your changes to the new XML file before you rename it.
4. Optional: Edit the mqwebuser.xml file to add users and groups. Assign those users and groups appropriate roles to be authorized to use the administrative REST API. You can also change the passwords for the users that are defined by default, and encode the new passwords. For more information, see Configuring users and roles.
Enable remote connections to the mqweb server:
- From version 9.0.4, use the setmqweb command:
  setmqweb properties -k httpHost -v hostname
- From version 9.0.1, add the following XML to the mqwebuser.xml file, within the <server> tags:
  <variable name="httpHost" value="hostname"/>
where hostname specifies the IP address, domain name server (DNS) host name with domain name suffix, or the DNS host name of the server where IBM MQ is installed. Use an asterisk, *, to specify all available network interfaces.
Attention:
Before issuing either the setmqweb or dspmqweb commands on z/OS, you must set the WLP_USER_DIR environment variable, so that the variable points to your mqweb server configuration.
To do this, issue 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.sh. For example:
export WLP_USER_DIR=/var/mqm/web/installation1
For more information, see Create the Liberty server definition.
Start the mqweb server that supports the REST API:
- On Windows and Linux, as a privileged user, enter the following command on the command line:
  strmqweb
- On z/OS, start the procedure that you created in Task 29: Create a procedure for the IBM WLP server.

What to do next

Choose how users of the administrative REST API authenticate with the mqweb server. You do not have to use the same method for all users. The following options are available:
- Let users authenticate by using HTTP basic authentication. In this case, a user name and password are encoded, but not encrypted, and sent with each REST API request to authenticate and authorize the user for that request. In order for this authentication to be secure, you must use a secure connection. That is, you must use HTTPS. For more information, see Using HTTP basic authentication with the REST API.
- Let users authenticate by using token authentication. In this case, a user provides a user ID and password to the REST API login resource with the HTTP POST method. An LTPA token is generated that enables the user to remain logged in and authorized for a set amount of time. In order for this authentication to be secure, you must use a secure connection. That is, you must use HTTPS. For more information, see Using token based authentication with the REST API.
- Let users authenticate by using client certificates. In this case, the user does not use a user ID or password to log in to the administrative REST API, but uses the client certificate instead. For more information, see Using client certificate authentication with the REST API.
Configure REST API settings, including enabling HTTP connections, and changing the port number. For more information, see Configuring the IBM MQ Console and REST API.
Optionally, configure the REST API for MFT. For more information, see Required configuration for the MFT REST API.
Optionally, configure Cross Origin Resource Sharing for the REST API. By default, you cannot access the REST API from web resources that are not hosted on the same domain as the REST API. That is, cross-origin requests are not enabled. You can configure Cross Origin Resource Sharing (CORS) to allow cross-origin requests from specified URLs. For more information, see Configuring CORS for the REST API.
Use the REST API. For more information, see Using the administrative REST API, Remote administration using the REST API, and the Administrative REST API reference.

Note: You can stop the mqweb server at any time by using the endmqweb command. However, if the mqweb server is not running, you cannot use the REST API or IBM MQ Console.