IBM Z and LinuxONE

Using the IBM Remote System Explorer APIs with the Zowe API Mediation Layer.

By Joe Winchester posted Wed April 14, 2021 06:08 PM

  

RSE API and Zowe API Mediation Layer


The Remote System Explorer (RSE) API provides REST APIs for z/OS services covering data sets, unix files, JES, TSO and a number of other mainframe services.  It is the URL endpoint for Open Mainframe Project's Zowe extensions for the RSE Command Line Interface (CLI) plugin, as well as the Visual Studio Code marketplace extension IBM Z Open Editor

The architecture diagram belows shows the two client interfaces (the Zowe RSE Command Line Interface and the Visual Studio Code Extension IBM Z Open Editor) either using the RSEAPI server directly to access z/OS services (the blue line), or else working behind the Zowe API Mediation Layer (the red line).  




This blog describes how to configure the RSE API server to register as a service to a Zowe API Mediation Layer, allowing routing of API requests and use of the Zowe single sign-on token.  One of the benefits of the Zowe API Mediation Layer (that is a Netflix Zuul server) is its ability to provide a single northbound edge URL endpoint for REST API requests and then route these to more than one instance of southbound servers, providing workload balancing and increased API throughput.  The configuration of this is also described in the section "Configuring Multiple RSEAPI instances".  

Configure RSE API for Zowe API Mediation Layer


Obtain the IBM Remote System Explorer API (RSE API) from https://ibm.github.io/mainframe-downloads/host-components.html#rse-api-host.
Follow the installation instructions in the RSE API Host Configuration . The RSE API is an Apache Tomcat server that has a configuration file  rseapi.env. This file contains the variable ZOWE_ML which should be changed to the URL of the Zowe API Gateway. This allows the RSE API server to make calls to the gateway for authentication purposes.

ZOWE_ML=https://tvt5003.svl.ibm.com:7554/

Register the RSE API server with the Zowe API Mediation layer


Zowe instances are configured with the configuration file
instance.env. This contains a number of customizable key values such as the port numbers and other runtime data passed to the Zowe runtime at startup. The RSE API uses static registration to the API Mediation layer by providing a USS file application.yml that contains registration details. The instance.env variable ZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES contains a semi colon separated list of directories that each contain a single application.yml static definition file.

ZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES=/var/usr/lpp/zowe/rse

Into the directory referred to above, in this example /var/usr/lpp/zowe/rse create an application,yml file and copy the contents from below.  Customize the three locations where the RSE API endpoint server is defined. These are instanceBaseUrls: , documentationUrl: and swaggerUrl: where the RSEAPI_HOST should be replaced with the actual TCP/IP host address and RSEAPI_PORT is the port number (by default 6800).

services:
    - serviceId: ibmrse # This is the first URL segment to identify RSE
      title: Remote System Explorer API
      description: Remote System Explorer (RSE) API
      catalogUiTileId: ibm-rse-api
      instanceBaseUrls:
          - https://<RSEAPI_HOST>:<RSEAPI_PORT>/rseapi 
      homePageRelativeUrl: / 
      routedServices:
          - gatewayUrl: api/v1
            serviceRelativeUrl: /api/v1/ # Note the slash at the start
      authentication:
          scheme: zoweJwt
      apiInfo:
          - apiId: com.ibm.rse
            gatewayUrl: api/v1
            version: 1.0.0
            documentationUrl: https:<RSEAPI_HOST>:<RSEAPI_PORT>/rseapi
            swaggerUrl: https://<RSEAPI_HOST>:<RSEAPI_PORT>/rseapi/api-docs/main-swagger.json
catalogUiTiles:
    ibm-rse-api:
        title: IBM Remote System Explorer
        description: The IBM RSE collection of REST APIs allows working with MVS data sets, z/OS UNIX files and commands, JES jobs, TSO commands, and other z/OS components.​

Sample application.yml static definition


In the following example the API Mediation Layer is running on
tvt5003.svl.ibm.com:26502 and the RSE API server is running on tvt5003.svl.ibm.com:6800

The /etc/zexpl/rseapi.env variable ZOWE_ML on line 92 is updated to be

ZOWE_ML=https://tvt5003.svl.ibm.com:26502/

and t
he directory  /var/usr/lpp/zowe/rse is created with the file application.yml contents below.

services:
    - serviceId: ibmrse # This is the first URL segment to identify RSE
      title: Remote System Explorer API
      description: Remote System Explorer (RSE) API
      catalogUiTileId: ibm-rse-api
      instanceBaseUrls:
          - https://tvt5003.svl.ibm.com:6800/rseapi 
      homePageRelativeUrl: / 
      routedServices:
          - gatewayUrl: api/v1
            serviceRelativeUrl: /api/v1/ # Note the slash at the start
      authentication:
          scheme: zoweJwt
      apiInfo:
          - apiId: com.ibm.rse
            gatewayUrl: api/v1
            version: 1.0.0
            documentationUrl: https://tvt5003.svl.ibm.com:6800/rseapi
            swaggerUrl: https://tvt5003.svl.ibm.com:6800/rseapi/api-docs/main-swagger.json
catalogUiTiles:
    ibm-rse-api:
        title: IBM Remote System Explorer
        description: The IBM RSE collection of REST APIs allows working with MVS data sets, z/OS UNIX files and commands, JES jobs, TSO commands, and other z/OS components.​

The file application.yml needs to be encoded in UTF-8. If when you look at the file using cat from ssh and you can see the file rendered then it is likely encoded in EBCDIC. Convert it with the iconv command, a sample of which is shown below which takes the input file application.ebcdic and converts it to UTF-8 characters in the output file application.yml.

iconv -f IBM-1047 -t ISO8859-1 application.ebcdic > application.yml​

Testing RSE API in the Zowe API Mediation Layer


The RSE API tile will be displayed on the API Catalog which can be accessed after logging into the API Gateway port (which defaults to 75544).



Selecting the catalog file will show the detail for the APIs rendered in based on their open API definition.



Selecting an API, such as GET jobs allows you to execute live API requests with the "Try it out" feature. The screen shot below the result after running an API to list all jobs beginning ZWE* for owner *.


The Request URL shows that the API request is: https://tvt5003.svl.ibm.com:26502/ibmrse/api/v1/jobs?prefix=ZWE%2A&owner=%2A which is directed to the API gateway running on 26502. The ibmrse is the service ID for the API, making it unique across the API Gateway's registered services, and the RSE API that actually serves the request is https://tvt5003.svl.ibm.com:6800/rseapi/api/v1/jobs?prefix=ZWE%2A&owner=%2A on its own 6800 port and with the apiID of rseapi.

Using the RSE CLI with the Zowe API Mediation Layer


The Zowe Command Line Interface RSE extension extension provides a sctiptable command interface to the RSE API server's REST APIs. A profile defines the connectivity details for the endpoint that provides the back end for the requests.

An example of the CLI is the command `zowe rse list jobs that can retrieve a list of jobs with prefix ZWE* for all owners.

zowe rse list jobs -o "*" -p "ZWE*"​

With the RSE API server running on port 6800 the Zowe profile details will contain the password for the user ID that is flowed on each REST API request, and also the explicit port of the RSE API server.

user: user
password: Password
host: tvt5003.svl.ibm.com
port: 6800
rejectUnauthorized: false
basePath: rseapi
protocol: https​


With the RSE API server as a registered service to a Zowe API Mediation Layer this allows the RSE profile to be used alongside Zowe CLI base profiles. A base profile defines the path to a Zowe API Mediation Layer and the RSE profile delegates to its base for connectivity details.

The RSE profile just contains the name of the baseProfile (default is there is only one) as well as the basePath matching the API service ID of the registered RSE API server, in our case ibmrse to match the value in the application.yml.

baseProfile: default
basePath: ibmrse​


In the default base profile the host and port of the API Mediation Layer are specified.

host: tvt5003.svl.ibm.com
port: 26502


The base profile doesn't contain any information yet about the user ID or password. To generate this enter the command zowe auth login apiml and type in the user ID and password. This will then contact the API mediation layer and generate the single sign-on JWT which is then stored in the base profile.


The base profile now contains a generated token

host: tvt5003.svl.ibm.com
port: 26502
tokenType: apimlAuthenticationToken
tokenValue: eyJhbGciOiJSUzI1NiJ9.eyJzdW.....​


The RSE API commands remain unchanged, so zowe rse list jobs -o "*" -p "ZWE*" will still return a list of all ZWE* prefixed jobs for all owners, however instead of using a password for the REST API request, the token is retrieved from the base profile and passed in the bearer data for the REST API request.


Configuring multiple instances of RSEAPI


If you wish to take advantage of workload balancing of REST API requests flowing through the API Mediation Layer, you can start up more than one instance of the RSEAPI server on multiple ports. For example, you could bring up one server on  6800  and two more on 6801 and 6802

In the application.yml file each independent RSEAPI instance can be defined in the instancebaseURLs: sectionWhen a REST API request is received by the API Mediation Layer, either from the RSE CLI , the IBM Z Open Editor, or perhaps another application coded to use the REST APIs,  it will be routed to the most available instance.  In a future blogpost I'll cover more detail on how to monitor and configure the REST API requests and control the routing rules.  

 instanceBaseUrls:
          - https://<RSEAPI_HOST>:6800/rseapi 
          - https://<RSEAPI_HOST>:6801/rseapi 
          - https://<RSEAPI_HOST>:6802/rseapi 


This blog has given an introduction to using the RSE client software,  the Zowe RSE plugin and the VS Code extension IBM Z Open Editor, to take advantage of the Zowe API Mediation Layer.  It has shown how this can benefit from token based authentication (aka single-sign on) and workload routing to allow the APIML to broker REST API requests from the client between multiple server instances.  



0 comments
21 views