Matt Leming
Published on 17/05/2019 / Updated on 20/05/2019
Zowe is an open source project that offers a modern set of interfaces for interacting with z/OS. These include a web based virtual desktop which includes a number of apps including a 3270 terminal; an API mediation layer which provides a gateway for exposing z/OS based REST APIs; and a command line interface to make it easier to access z/OS remotely using common tools.
Zowe is a natural exploiter of the various web based technologies that are available in recent releases of MQ, such as the MQ Console and the REST API. In this blog I want to describe how to add the MQ REST API to the Zowe API Mediation Layer. While the MQ REST API could be exposed separately there is significant value in using the Zowe API Mediation Layer as a single access point for all z/OS REST APIs.
When I tried this out I used MQ for z/OS 9.1.2 and Zowe 1.0.0. The same instructions should work with MQ for z/OS V9.1.0 or later, and more recent versions of Zowe.
I have assumed that both Zowe and IBM MQ, including the mqweb server, have previously been installed, configured and started. Information on installing Zowe is here; information on configuring the mqweb server on z/OS is here.
Step 1: Install the REST API into the API mediation layer
This is a relatively simple operation that requires following the instructions provided here with the MQ REST API used as the API to be exposed and routed.
If you follow those steps you will end up with a YAML file which will look similar to the example below. The example uses MQ 9.1.2 as that is the most recent version of MQ available. Using an alternative version, such as MQ 9.1.0 would require minimal changes to the values of the serviceId, title, description and apiId keys.
services: - serviceId: ibmmq912 catalogUiTileId: ibmmq912 title: IBM MQ 9.1.2 REST API description: The IBM MQ 9.1.2 REST API instanceBaseUrls: - https://
mqwebhost:
mqwebport/ibmmq/rest routes: - gatewayUrl: api/v1 serviceRelativeUrl: /v1 apiInfo: - apiId: com.ibm.ibmmq912 gatewayUrl: api/v1 documentationUrl: https://
mqwebhost:
mqwebport/api/explorer/ version: 1.0.0catalogUiTiles: ibmmq912: title: IBM MQ 9.1.2 REST API description: Provides access to the IBM MQ administrative REST API which can be used to administer IBM MQ queue managers, and the IBM MQ messaging REST API which can be used to send messages to, and receive messages from, queues.
Before using the example YAML change the value of mqwebhost and mqwebport to those used by the mqweb server hosting the REST API.
The YAML file will result in calls to the Zowe API Mediation Layer at the https://zowehost:zoweport/api/v1/ibmmq912/ URL being mapped to the MQ REST API at the https://mqwebhost:mqwebport/ibmmq/rest/v1/ URL.
The documentationUrl key points to the API explorer capability that is built in to the mqweb server. However, the API explorer is not enabled by default. To enable it follow these instructions.
Once the YAML file has been created the instructions describe how to install it into API mediation layer, and how to verify the installation worked.
Step 2: Ensure that the API mediation layer trusts the certificate used by the REST API
The API mediation layer needs to trust the certificate of each service that it provides access to. Follow these instructions for the certificate used by the mqweb server.
Step 3: Validate that the REST API is visible in the API catalog
Validate that the MQ REST API has been successfully added to the API mediation layer by opening the Zowe Virtual Desktop and then launching the API catalog. The MQ REST API should now be visible in the API catalog next to the other APIs, as shown below.
You can then click on the MQ REST API tile to go view the API documentation.
Step 4: Try accessing the REST API via the API mediation layer
Accessing the REST API via the API mediation layer is very similar to accessing the API without Zowe being used. The only real difference is the URL. Authentication and authorization use the existing capabilities of the MQ REST API.
The following example shows how to use curl to list available queue managers via the API mediation layer. In the example, basic authentication is used to provide a user ID and password which is validated by the mqweb server before the API can be called. Reference documentation for this operation can be accessed via the documentation URL provided by the Zowe API Catalog, or via the MQ Knowledge Centre.
curl -i -k https://zowehost:zoweport/api/v1/ibmmq912/admin/qmgr -u mquserid:mqpassword HTTP/1.1 200Content-Language: en-USContent-Type: application/json;charset=utf-8Transfer-Encoding: chunkedDate: Thu, 09 May 2019 12:30:38 GMT{"qmgr": [ { "name": "MQ21", "state": "running" }, { "name": "MQ26", "state": "running" }]}
While this is a simple example, it proves that all of the MQ REST API has been successfully added to the Zowe API Mediation Layer and is now available with the other REST APIs provided by Zowe. All you need to do is start using them!