IBM Z and LinuxONE - Group home

Playing with APIs using IBM Remote System Explorer API

IBM Explorer for z/OS|Dave McKnight|Nov 3, 2020

  
While its inaugural release was just over a few months ago,  IBM Remote System Explorer API has covered a lot of new ground with the latest edition.  Besides offering modern, easy access to MVS data sets, UNIX files and jobs, RSE API now supports TSO commands, MVS searches, streaming file transfers and more.  If you use IBM Developer for z/OS, IBM Explorer for z/OS or other Aqua products, then you probably already have the requisite z/OS Explorer server.  If you use IBM Wazi Developer for VS Code or IBM Wazi Developer for Workspaces then you may already be leveraging the RSE API plugin for the Zowe CLI to communicate with the RSE API server.  However, even if you don't have a dedicated client, you can still work with these APIs, directly. 

Of course you need to have the server running first.  A sysprog can install and configure RSE API in much the same way as the z/OS Explorer (RSE) server.  RSE API uses the same underlying libraries and technologies to interact with the mainframe but in a modern way via HTTP requests and JSON objects.  In order to use the APIs, you need a way to understand what they do and how to call them.  RSE API uses the Open API Specification so you can discover and try out APIs via Swagger UI.   With the RSE API server running, the API docs can be accessed via a URL in this form:
https://<hostname>:<port>/rseapi/api-docs

As of version 1.0.2, the Swagger API docs look like this:

Drill down to discover and experiment with the APIs.  For example, expand MVS Datasets and find the GET /datasets/{filter} API.  To test it out, simply click the "Try it out" button, enter a data set name filter and press the execute button.  If this is your first time testing one of these APIs, you will get prompted for your host ID and password.  The curl command Swagger uses to exercise an API is shown under Responses section along with the result in the Response body field beneath it.

Let's say you want to run an arbitrary UNIX command on z/OS.  Browse into UNIX Commands, specify the path and invocation, and press execute to run.  In the following example, the netstat command was run:

Like the GET /datasets/{filter} API, the PUT /unixcommands/ API conveniently provides a response in JSON format.  Using JSON is handy because it is common industry practice and most modern programming languages provide the means to easily parse and generate it.

The TSO Commands API lets you run TSO commands in a way similar to the UNIX Commands API.  The Swagger provides a text field where you can specify the command.  There's also a header request option that lets you display output in pretty or flat format.

Again, the results of the command are displayed in the response body using JSON format.

Another capability that you may find useful are the MVS Search APIs.  Suppose you're looking for instances of a particular textual pattern in members of a partitioned data set.  Say you're looking for occurrences of IHBINNRR within SYS1.MACLIB.  Navigate to GET /datasets/search/PDSMembers and specify the search parameters as follows.

The result is a JSON indicating where each match can be found:

For an end user, there's a lot of response data here to sift through but the Swagger UI is ultimately there to help developers.   The real value for the end user and the organization arrives when developers write tools or scripts that exploit these APIs.

IBM RSE API is free and there are a couple ways to get it.  First, you'll need either the 3.1 or 3.2 version of the z/OS Explorer host component as a prerequisite.  You can download RSE API from here or you can order it from ShopZ (PID 5655-EX1).