REST API discovery

Documentation for the REST API is available within the 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 (apiDiscovery) on the mqweb server.

Before you begin

[Stabilized]
Important: The apiDiscovery feature has been stabilized. You can still use this feature. At present, IBM MQ does not support the use of the mpOpenAPI feature.

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 IBM MQ Console and REST API security.

Procedure

  1. Locate the mqwebuser.xml file in one of the following directories:
    • [AIX, Linux, Windows]MQ_DATA_PATH/web/installations/installationName/servers/mqweb
    • [z/OS]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 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 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 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. Use the dspmqweb status command to view the URL.