With the release of RSE API 1.0.8, we're pleased to announce some new capabilities.  Let's take a look at what you can do now...

MVS Data Set Queries with Custom Attributes

The API for querying MVS data set properties produces a JSON response with a number of attributes for each data set.  While these attributes are useful, you don't always need them all.  Sometimes you just care about specific ones like name and type.  RSE API 1.0.8 provides an optional Included-Attributes header that lets you specify which attributes to get back so that you can ask for precisely what you want.  This makes for cleaner API consumption use cases and, depending on the attributes you ask for, it can affect performance too.  

As an example, take the following data set query (where the optional Included-Attributes header is not included):


The resulting JSON looks like this, with a complete set of attributes:

Take that same query and specify the header Included-Attributes=name,creationDate to hone in on the attributes you're looking for.
curl -X 'GET' \
'https://mymainframe:6800/rseapi/api/v1/datasets/TST.LEARN.ASM.*' \
-H 'accept: application/json' \
-H 'Included-Attributes: name,creationDate'
In this case, the results look like the following:

Common Properties

Have you ever longed for an easy way to share and access information pertaining to a z/OS system with your team?  For example, there are several services of interest running on the mainframe and members of your team want to know which ports correspond to which services.  With some detective work on the system, this kind of information can be uncovered but, in doing so, folks are likely to stumble down tedious and time-consuming rabbit holes.  It would be nice if there were some central place that publishes this kind of information... even nicer if you could work with this data using REST APIs.

Enter Common Properties.  It is a new service intended to help facilitate information sharing without adding unnecessary complexity.  Think of it as a sort of bulletin board for collaborative information management.  At your local coffee shop, patrons can post brochures or flyers on a bulletin board to advertise community events.  The overhead is low and a reasonable degree of trust is granted to posters.  Similarly, the intention with common properties is to allow your team to crowdsource common information pertaining to your z/OS system with minimum overhead.  Different users can independently contribute properties to the shared pool of common data.  

Without having to install and configure a database, RSE API provides all the APIs needed to do this.  To enable Common Properties, your sysprog has to set the RSE_COMMON_PROPERTIES variable in the rseapi.env file, pointing to a z/OS UNIX folder that is accessible to the members of your team, and then restart the server.  For example:
RSE_COMMON_PROPERTIES=/usr/shared/common.properties
That's it for enablement!  To populate data, you need at least one namespace and there's an API to do that.  APIs are also provided to get and manipulate data for a given namespace.  Users can query specific data within JSON trees or surgically merge new data into them.   

For example, you can use POST/commonproperties/ports to create a new namespace that will contain information about 'ports'.  You can then use PUT/commonproperties/ports to contribute JSON content to the 'ports' namespace.  Consumers can use GET/commonproperties/ports to fetch information that has been contributed to the 'ports' namespace.  Under the covers, it comes down to manipulating a UTF-8 file, in this case, called /usr/shared/common.properties/ports.json.  Note that, since we're just dealing with z/OS UNIX files, you can also import existing JSON files into the common properties folder and they'll become readily available as namespaces. 

Suppose you want to fetch data about a particular set of services, say 'debug'.  You could make the following call to obtain that from the 'ports' namespace: 
curl -X 'GET' \
'https://mymainframe:6800/rseapi/api/v1/commonproperties/ports?jsonPath=/debug' \
-H 'accept: application/json'

A subset of the complete 'ports' namespace comes back that represents debug-related info:

If you just want a particular port, you can qualify it further:
curl -X 'GET' \
'https://mymainframe:6800/rseapi/api/v1/commonproperties/ports?jsonPath=/debug/remote_debug_service_port' \
-H 'accept: application/json'

And now you get back just the one port:

By being able to zero in on a specific portion of a namespace, a client can easily pull out and programmatically leverage that information.

Here the list of Common Properties APIs in the Swagger documentation:

The following shows a sample front-end application that uses the Common Properties service for sharing and accessing host service information.  The left side of the panel is a set of controls for managing ports while the right side shows the full contents of the namespace being used. 

Interactive TSO Commands

In previous versions of RSE API, only Legacy ISPF Gateway was supported.  There was no API facilitating reuse of a TSO session for multiple commands and there was no support for interactive commands and scripts. With IBM Explorer for z/OS client/server scenarios, RSE supports the Interactive ISPF Gateway where the client prompts users for TSO logon information when establishing a connection.  For a pure REST API like RSE API, any API can be used to establish a session which makes prompting for TSO logon information more of a challenge, especially if a user isn't planning on calling any TSO commands.

If you want to be able to use interactive TSO commands, starting in RSE API 1.0.8, the sysprog can configure fixed TSO logon values in the rseapi.env file.  The new options used to specify these values are as follows:

Note: There are formatting differences between CEA (interactive) and legacy TSO commands.  For more information about those differences go here. 

When interactive TSO commands are enabled, users can run commands like the following, providing a shell-id in order to be able to reuse the TSO session.

curl -X 'PUT' \
'https://mymainframe:6800/rseapi/api/v1/tso?command=TSO XMIT M168.IBMUSER DA('USER.CLIST')' \
-H 'accept: application/json' \
-H 'prettyOutput: true' \
-H 'shell-id: abc'
curl -X 'PUT' \
'https://mymainframe:6800/rseapi/api/v1/tso?command=TSO RECEIVE' \
-H 'accept: application/json' \
-H 'prettyOutput: true' \
-H 'shell-id: abc'

That results in the following output.