REST API discovery

Documentation for the REST API is available within the IBM Knowledge Center and in Swagger format. Swagger is a commonly used approach for documenting REST APIs. The Swagger documentation for the REST API can be viewed by enabling the API discovery feature on the mqweb server.

Before starting

We must enable security for the mqweb server to view the Swagger documentation by using API discovery. For more information about the steps that are required to enable security, see IBM MQ Console and REST API security.

Procedure

1. Locate the mqwebuser.xml file in one of the following directories:
   • MQ_DATA_PATH/web/installations/installationName/servers/mqweb
   • WLP_user_directory/servers/mqweb

     Where WLP_user_directory is the directory that was specified when the crtmqweb script ran to create the mqweb server definition.

2. Add the appropriate XML to the mqwebuser.xml file:
   • If the <featureManager> tags exist in your mqwebuser.xml file, add the following XML within the <featureManager> tags:

     <feature>apiDiscovery-1.0</feature>

   • If the <featureManager> tags do not exist in your mqwebuser.xml file, add the following XML within the <server> tags:

     <featureManager>
          <feature>apiDiscovery-1.0</feature>
     </featureManager>

3. View the Swagger documentation by using one of the following methods:
   • Display a web page that we can browse and try out the REST API by entering the following URL in a browser:

     https://host:port/ibm/api/explorer

     In addition to authenticating each request, we must include a ibm-mq-rest-csrf-token header for each POST, PATCH, or DELETE request. The contents of this header can be any string, including blank.

     This request header is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.

   • Retrieve a single Swagger 2 document that describes the whole REST API by issuing an HTTP GET to the following URL:

     https://host:port/ibm/api/docs

     This document can be used for applications where we want to programmatically navigate the available APIs.

   host

   Specifies the host name or IP address that the REST API is available on.

   The default value is localhost.

   port

   Specifies the HTTPS port number that the administrative REST API uses.

   The default value is 9443.

   If the host name or port number is changed from the default, we can determine the correct values from the REST API URL. Use the dspmqweb status command to view the URL.

Parent topic: Administration using the REST API