Configuring the messaging REST API

By default, the mqweb server which hosts the IBM® MQ Console and REST API has the messaging REST API enabled. From IBM MQ 9.2.0, connections to IBM MQ from the messaging REST API are pooled, with 20 connections available for each queue manager. When all connections are in use, the messaging REST API creates a new, non-pooled connection to use for the request. You can change the maximum number of pooled connections, and the behavior of the messaging REST API when all connections are in use by using the setmqweb properties command. You can also configure whether messaging is enabled by using the setmqweb properties command.

Before you begin

To complete this task, you must be a user with certain privileges so that you can use the dspmqweb and setmqweb commands:

• On z/OS®, you must have authority to run the dspmqweb and setmqweb commands, and write access to the mqwebuser.xml file.
• On all other operating systems, you must be a privileged user.

To use the messaging REST API the caller must be authenticated to the mqweb server and must be a member of the MQWebUser role. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API. The caller must also be authorized to access queues used for messaging through OAM orRACF®. For more information about security for the REST API, see IBM MQ Console and REST API security.

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. For example:

export WLP_USER_DIR=/var/mqm/web/installation1

For more information, see Create the mqweb server.

About this task

You can configure whether messaging is enabled by using the setmqweb properties command.

To optimize the performance of the messaging REST API, connections to IBM MQ queue managers are pooled. That is, instead of each REST request creating, using, and destroying its own connection, each REST request uses a connection from a connection pool. By default, 20 connections are available for each queue manager pool, and there are three options for handling requests when all the connections are in use:

• The messaging REST API can create a new, non-pooled connection to use for the request. This behavior is the default behavior.
• The messaging REST API can return an error.
• The messaging REST API can wait for a pooled connection to become available. This wait is an indefinite wait.

You can change the maximum number of pooled connections and the default behavior of the messaging REST API when all connections are in use by using the setmqweb properties command.

• View the current configuration of the HTTP messaging REST API by using the following command:

  dspmqweb properties -a

  The mqRestMessagingEnabled field shows whether the messaging REST API is enabled. The value is True is the messaging REST API is enabled, or False otherwise. For more information, see dspmqweb.
• Configure the messaging REST API by using the following command:

  setmqweb properties -k mqRestMessagingEnabled -v enabled

  where enabled is the value true if you want the messaging REST API enabled, or false otherwise.

• Configure connection pooling for the messaging REST API:
  • Configure the maximum connection pool size for each queue manager pool by using the following command:

    setmqweb properties -k mqRestMessagingMaxPoolSize -v size

    where size specifies the size of the pool.

    Note: If a large value for mqRestMessagingMaxPoolSize has been set, and a large number of queue managers are being connected to, you should consider increasing the maximum size of the mqweb server heap.

    See tuning the mqweb server JVM for more information.

  • Configure the behavior of the messaging REST API when all the connections within the pool are in use by using the following command:

    setmqweb properties -k mqRestMessagingFullPoolBehavior -v action

    where action specifies the action to take. action can be one of the following values:

    block

    When all the connections in the pool are in use, wait for a connection to become available.

    error

    When all the connections in the pool are in use, return an error.

    overflow

    When all the connections in the pool are in use, create a non-pooled connection to use, and dispose of the connection after it is used.