REST assured, REST APIs for z/OS is the way!

In the recent Dynamic Workload Console v9.4 FP2 release, a new powerful feature has been added: the possibility to handle the interaction with your z/OS workload through REST APIs! 

REST APIs give you the possibility to perform actions and queries on your workload, such as: 

• Retrieve useful data from your Current Plan (query Operations and Applications, using also specific filters to narrow down your queries). 

• Perform changes in your Current Plan (Hold, Release, NOP, UNNOP and many more). 
• Query data available in your Application Database. 
• Create, modify, and delete objects in your Application Database. 
  
  

All this can be performed in a simple, safe, and quick way by using REST APIs.

Simple: REST APIs are simple to use, requiring just a URL and few parameters as input.

Safe: leveraging on HTTPS connection and basic authentication, all your data is protected in both sending and receiving ways. 

Quick: response time of a REST API call is in seconds!  

Let’s explain first what is the RESTful approach we have used to create this new functionality. 

Representational state transfer (REST) or RESTful Web Services is a way of providing interoperability between computer systems on the Internet. REST-compliant Web Services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.  

In a RESTful Web Service, requests made to a resource's URI will elicit a response that may be in XML, HTML, JSON or some other defined format. The response might confirm that some alterations have been made to the stored resource, and it might provide hypertext links to other related resources or collections of resources. Using HTTP, which is the most common format, the kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE, and so on. 

Using this approach, REST API for z/OS have been created and included in the ZConnector which is shipped with the Dynamic Workload Console. 

The product documentation shows all the REST APIs available both on Application Database and Current Plan, specifying the path you must use to invoke a specific REST API, the required input parameters, and the expected output. After installing DWC v9.4 FP2 you can find the documentation of the RESP APIs at the following address: https://<DWC_HOST>:<port_number>/twsz,  where: 

• DWC_HOST is the hostname of your Dynamic Workload Console. 
• port_number is the HTTPS port number of your Dynamic Workload Console. The default is 16311.

REST APIs for z/OS have been organized following a specific URL pattern which guides you to identify the object to interact with or the action to be performed:

/{engine name}/{sector}/{object type}/{object id}/{action} 

Engine name: Since REST APIs leverage on existing ZConnector connection, in this field you must set the engine name chosen when this connection was defined. This name is the one defined through wastools scripts during the execution of the createZosEngine script. 

Sector: In this field, you must specify the keyword <model> for Application Database or <plan> for Current Plan.

Object type: In this field, you must specify which type of object you want to interact with. Keywords will be jobstream, job, resource, calendar, and so on. 

Action: In this field, you must enter the name of the action that will be performed on the object type previously specified. Keywords are: query, release, hold, release all dependencies, and many more. 

Object id: This field identifies specifically the object that you want to interact with, using the id of the object to be processed by REST APIs. 

Here are some examples of REST APIs for z/OS, by using cURL which is a command line tool for transferring data with URL syntax:

Select all jobs in the Current Plan that are on hold:  

URL: https://<DWC_HOST>:16311/twsz/<ZOS_ENGINE_NAME>/plan/current/job/query

Remove the hold status on a specific Job in the Current Plan: 

URL: https:// <DWC_HOST>:16311/twsz/<ZOS_ENGINE_NAME>/plan/current/job/<JOB_ID>/action/release

Note: JOB ID can be retrieved from job information when you perform a query)

NOP a job in the Current Plan: 

URL: https:// <DWC_HOST>:16311/twsz/<ZOS_ENGINE_NAME>/plan/current/job/<JOB_ID>/action/nop

Note: (JOB ID can be retrieved from job information when you perform a query)

Select all jobs in the Current Plan with a wildcard.  For example, select all jobs that begin with GB*: 

URL: https://<DWC_HOST>:16311/twsz/<ZOS_ENGINE_NAME>/plan/current/job/query

If you have any questions, doubts or feedback on this article feel free to contact Gabriele Barboni at gabriele.barboni@hcl.com or Davide Canalis at davide.canalis@hcl.com. 

Gabriele Barboni
Senior Software Engineer & Developer at HCL
Connect with me on Twitter and  LinkedIn 

Email: gabriele.barboni@hcl.com

Gabriele Barboni is a Senior Developer experienced in full-stack web development.
He has worked in the Workload Automation industry since 2013 and is currently based in the HCL Products and Platforms Rome Software Development laboratory. He has a background in computer science technologies and he loves to travel and visit new places.





Davide Canalis
Software Engineer at HCL
Email: davide.canalis@hcl.com

Davide works as a Software Engineer at HCL Products and Platforms in Rome software development laboratory and he is a member of z/OS development team since April 2017.
He graduated in Mathematics in Rome where he lives and cultivates his passions for books and football.