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 you begin

You 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 Configure IBM MQ Console security.

Procedure

1. Locate the mqwebuser.xml file 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.

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, you must include a ibm-mq-rest-csrf-token header for each POST, PATCH, or DELETE request.

     The required contents of this header varies, depending upon the version of IBM MQ:

     • From Version 9.0.5, the ibm-mq-rest-csrf-token HTTP header needs to be present in the request; its value can be anything including blank.
     • Prior to Version 9.0.5, the value of the header is the content of the csrfToken cookie. A csrfToken is generated when an HTTP GET method is used with the REST API. We can view the contents of cookies by entering the following text into the address bar of your browser:

       javascript:alert(document.cookie)

     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 you 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. For more information about determining the URL, see Determining the REST API URL.