REST API discovery

Documentation for the REST API is available in IBM® Documentation 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.

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 you 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 IBM MQ 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 IBM MQ 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. You 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, you can determine the correct values from the REST API URL. For more information about determining the URL, see Determining the REST API URL.