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.
Before you begin
Important: The API Discovery feature has been stabilized and 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 Configuring IBM MQ Console security.
Procedure
-
Locate the mqwebuser.xml file in one of the following directories:
-
Add the appropriate XML to the mqwebuser.xml file:
-
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:
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.