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 the 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.