WORKLOAD AUTOMATION COMMUNITY
  • Home
  • Blogs
  • Forum
  • Resources
  • Events
  • About
  • Contact
  • What's new

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

2/6/2018

8 Comments

 
Picture
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.
Picture
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 [email protected] or Davide Canalis at [email protected]. 


Picture
Picture
Gabriele Barboni
Senior Software Engineer & Developer at HCL
Connect with me on Twitter and  LinkedIn 
Email: [email protected]

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: [email protected]

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.



8 Comments
Rich Szabo
6/15/2018 08:16:19 am

What is the minimum PTF level for IWS for z/OS that will allow the REST API to function?
Rich

Reply
Davide
6/19/2018 08:33:35 am

Hi Rich,
the minimum required level for enabling z/os rest api is DWC 9.4.0.2 fixpack. In order to make DWC 9.4.0.2 work correctly with z/os controller you will need to install APAR PI85255 if you have a z/os controller version which is 9.2 or earlier, otherwise you will need to install APAR PI85254. Moreover, if you are going to switch to DWC 9.4.0.3 fixpack and your z/os controller level is 9.3, you will need to install APAR PI93525. We strongly suggest you to install DWC 9.4.0.3 since it contains several fixes specifically for z/os rest apis.

Reply
resume writing service help link
1/24/2019 07:35:51 am

If I work in Information Technology industry, I am sure that I will be familiar with this one. But since I don't, I have to read the whole article first for me to get the gist of the story and all the stuff that is related to Representational state transfer (REST) or RESTful Web Services! Well, it is good to know that such thing has been existing already. It makes the process easier between internet and people. Technology has been taking over, and I cannot help but to be happy with everything that is happening around us. I can finally say that its a good thing!

Prema
7/27/2018 07:53:29 am



We are trying to implement rest API ,Is there an option to choose between mainframe and distributed while trying to connect to an engine ..

Prema

Reply
Davide
8/8/2018 02:38:54 am

Hi Prema,
you don't have an option such as the one you mentioned because z/OS and distributed rest api lie on two different component. Distributed apis are shipped within the distributed master, while z/OS apis reside on zConnector component that you install together with DWC.
Apart from this, the only difference between them is in the path you have to invoke:
https://<DWC_HOST>:16311/twsz/v1/<ZOS_ENGINE_NAME>/... for z/OS,
https://<ENGINE_HOST>:31116/twsd/.. for distributed.
Please note that "v1" part of the path in the z/OS api is present only from the 9.4 fixpack 3 release of the DWC.

Reply
Vishal
10/15/2019 03:16:15 am

How can we access IWSz REST APIs directly from home grown java based application? What is the minimum requirement from Installation perspective on z/OS?

Reply
Davide
10/25/2019 08:59:55 am

Hi Vishal,
to access rest api from a java app you basically need to compose the correct combination of http method and URL and then issue an http call against it. The z Connector (an application shipped within DWC) hosts rest api endpoints.
On z/OS side there is no particular requirement: if you are already able to interact with DWC you can invoke rest api.
Obviously, as mentioned in a comment above, there could be the need to install a compatibility apar on z/OS side, you need to check on DWC manual to know if any apar is required at your maintenance level on z/OS side.

Reply
Vishal
11/8/2019 12:16:25 am

Thanks for your response. I have explored it further and went through below mentioned two links. I was not able colclude if REST APIs are available to retrieve the Abended job details from error list and Edit the JCL.

I did find APIs signature for cancel, hold, rerun etc..

Can you please assist me on this or share any other link to documentation?

Driving IBM Workload Scheduler with REST API:
https://www.ibm.com/support/knowledgecenter/en/SSRULV_9.5.0/com.ibm.tivoli.itws.doc_9.5/common/src_dgd/awsddrestapi.htm

IBM Workload Automation REST API:
https://start.wa.ibmserviceengage.com/twsd/


Your comment will be posted after it is approved.


Leave a Reply.

    Archives

    March 2025
    February 2025
    January 2025
    December 2024
    November 2024
    October 2024
    September 2024
    August 2024
    July 2024
    June 2024
    May 2024
    April 2024
    March 2024
    February 2024
    January 2024
    October 2023
    August 2023
    July 2023
    June 2023
    May 2023
    April 2023
    March 2023
    February 2023
    January 2023
    December 2022
    September 2022
    August 2022
    July 2022
    June 2022
    May 2022
    April 2022
    March 2022
    February 2022
    January 2022
    December 2021
    October 2021
    September 2021
    August 2021
    July 2021
    June 2021
    May 2021
    April 2021
    March 2021
    February 2021
    January 2021
    December 2020
    November 2020
    October 2020
    September 2020
    August 2020
    July 2020
    June 2020
    May 2020
    April 2020
    March 2020
    January 2020
    December 2019
    November 2019
    October 2019
    August 2019
    July 2019
    June 2019
    May 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    July 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    December 2017
    November 2017
    October 2017
    September 2017
    August 2017
    July 2017
    June 2017
    May 2017

    Categories

    All
    Analytics
    Azure
    Business Applications
    Cloud
    Data Storage
    DevOps
    Monitoring & Reporting

    RSS Feed

www.hcltechsw.com
About HCL Software 
HCL Software is a division of HCL Technologies (HCL) that operates its primary software business. It develops, markets, sells, and supports over 20 product families in the areas of DevSecOps, Automation, Digital Solutions, Data Management, Marketing and Commerce, and Mainframes. HCL Software has offices and labs around the world to serve thousands of customers. Its mission is to drive ultimate customer success with their IT investments through relentless innovation of its products. For more information, To know more  please visit www.hcltechsw.com.  Copyright © 2024 HCL Technologies Limited
  • Home
  • Blogs
  • Forum
  • Resources
  • Events
  • About
  • Contact
  • What's new