Name: Restful-APIs-using-zOS-Connect
Owner: International Business Machines
Description: In this code we show how to create efficient and scalable RESTful APIs for mobile and cloud applications securely from your business critical applications residing on the mainframe using z/OS Connect
Created: 2017-05-18 21:18:09.0
Updated: 2018-03-09 22:55:23.0
Pushed: 2017-12-19 03:31:43.0
Homepage: https://developer.ibm.com/code/patterns/turn-your-mainframe-into-an-api-powerhouse/
Size: 2050
Language: null
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
In this code we show how to create efficient and scalable RESTful APIs for mobile and cloud applications securely from your business critical applications residing on the mainframe.
IBM z/OS Connect Enterprise Edition provides access to z/OS subsystems, such as CICS, IMS, WebSphere MQ, DB2, and Batch, that use RESTful APIs with JSON formatted messages. The framework provides concurrent access, through a common interface, to multiple z/OS subsystems.
z/OS Connect EE can help to deliver benefits for an enterprise in two ways.
In this journey we will show how to use z/OS Connect EE to create, deploy, and test RESTful APIs that expose z/OS subsystems
Scenario One: Expose a CICS COBOL program as a RESTful API
Scenario Two: Expose an IMS application as a RESTful API
z/OS Connect Enterprise Edition
CICS
IMS
Swagger
To request a trial, go to z Systems trial homepage. On this page, navigate to the z/OS Connect Enterprise Edition panel on the right. In the panel, click “register now” button and follow the steps. If everything goes through, you shoud see a screen titled “Congratulations, your environment is on its way”.
Wait for an email notification from “zTrial”.
The waiting normally lasts several hours to one business day.
The trial is available through a Windows-based remote desktop environment.
In order to access the trial environment, you must be able to connect to a remote system over a network connection.
IBM® z/OS Connect Enterprise Edition (z/OS Connect EE) makes exposing a CICS® program through a RESTful API quick and easy.
This scenario guides you through the steps in roughly 30 minutes. By the end of the session, you'll know how to:
No previous knowledge of CICS, z/OS Connect EE, or API design is needed, but some awareness of API terminology might help.
Please wait a moment while your development environment loads (this takes about 20 seconds).
Create an API project that will contain your API and service mapping.
Before you create your API, you must create a new API project. A z/OS® Connect EE API Project contains files that represent the API, and the mappings from the API to the services.
On the development environment menu bar, click File > New > Project… to open the New Project wizard.
Expand the z/OS Connect Enterprise Edition folder, select z/OS Connect EE API Project, and click Next.
Complete the fields as follows:
Click Finish to create the project in the Project Explorer.
Create a basic API that uses RESTful principles.
In the Path field, replace /newPath1
with the value /items/{itemID}.
Remove the POST, PUT, and DELETE methods for this path by clicking the X icon associated with each method.
This leaves the GET method. The GET method is typically used for retrieving data, which is the purpose of your API.
Associate your API to a Service Archive file.
In z/OS Connect EE, a service archive file (.sar
file) provides information about the underlying service, including its expected request and response JSON schemas.
Note: z/OS Connect EE provides tooling to generate .sar files for its compatible subsystems (including CICS®, IMS?, DB2®, and IBM® MQ).
In this scenario, the .sar
file is already generated, so you can focus on creating, deploying, and testing your API.
Click Service….
Click File System.
Browse to C:/Service Archive Files
.
Select the inquireSingle.sar
file and click Open.
In the dialog box that opens, click OK to confirm the import.
Click OK.
The inquireSingle
service is now associated with the get method of your API.
inquireSingle
service.
In this scenario, the connection between z/OS Connect EE and CICS is configured for you (using the WOLA service provider).
The final step is to configure the mappings between your new API and the inquireSingle
service, which represents the CICS COBOL program logic.
Map your API parameters to fields in the associated service.
inquireSingle
service, and to remove redundant fields from the API documentation.
Next to the GET method, click Mapping… then click Open Request Mapping.
Right-click ca_request_id
, then click Add Assign transform.
In the Properties view, at the bottom of the window, click General and set Value to 01INQS.
Leave the Omit from interface option checked to exclude this value from the API documentation.
Expand the field ca_inquire_single
so that the sub-field ca_single_item
is visible.
Select the fields ca_return_code
, ca_response_message
, and ca_single_item
.
Right-click one of the selected fields, then click Add Remove transform.
Connect the path parameter itemID to the field ca_item_ref_req
by clicking and dragging one to the other.
A Move action is created that assigns the path parameter itemID
in the HTTP request to the field ca_item_ref_req
in the service's JSON content.
Click File > Save from the menu to save your progress.
Close the request tab.
Remove irrelevant values from the response so that your API returns relevant fields only.
inquireSingle
contains several fields that aren?t relevant to that request.
You can safely remove these fields to make the API response and the API documentation clearer.
Click Mapping… for the GET method, then click Open Response Mapping.
Expand the field ca_inquire_single
so that the sub-field ca_item_ref_req
is visible.
On the right side of the window, select the ca_request_id
and ca_item_ref_req
fields.
Right-click one of the selected fields, and select Add Remove transform.
This excludes these fields from the body of the response.
Package and deploy your API from within the API Editor.
In the Project Explorer view, select your API project (catalog) and right-click to select .
Optional: If the z/OS Connect EE server is disconnected, connect to the server by clicking on the red icon at the top of the Deploy API dialog.
Click OK to deploy your API.
When deployment completes, click OK on the Result dialog box.
Test your API by using the built-in Swagger UI.
You can use the built-in Swagger UI to test out an API from within the developer environment. Let's try that now by opening up the Swagger UI for your new API, and request information about an item in the catalog.
In the z/OS Connect EE Servers view, expand the API folder, right-click your API, and click Open in Swagger UI.
In the tab that opens, click default, and then /items/{itemID}
The CICS application that you have exposed by creating this API contains an inventory of office stationary. A 24-pack of black ball pens has an itemID
of 10.
You can use your new API to check the price and stock levels of this item.
Type the value 10 in the relevant text box, then click Try it out.
Congratulations! You've successfully exposed a CICS® application as a RESTful API by using z/OS Connect EE!
IBM® z/OS Connect Enterprise Edition (z/OS Connect EE) makes exposing an IMS? application through a RESTful API quick and easy.
This scenario guides you through the steps in roughly 30 minutes. By the end of the session, you'll know how to:
No previous knowledge of IMS, z/OS Connect EE, or API design is needed, but some awareness of API terminology might help.
Please wait a moment while your development environment loads (this takes a minute or so).
Create an API project that will contain your API and service mapping.
Before you create your API, you must create a new API project. A z/OS® Connect EE API Project contains files that represent the API, and the mappings from the API to the services.
On the development environment menu bar, click File > New > Project… to open the New Project wizard.
Expand the z/OS Connect Enterprise Edition folder, select z/OS Connect EE API Project, and click Next.
Complete the fields as follows:
Click Finish to create the project in the Project Explorer.
Create a basic API that uses RESTful principles.
You'll create an API that a consumer can use to add contact information to the phone book program. The API will connect through a service to the program in IMS?.
In the Path field, replace /newPath1 with the value /contacts.
Remove the GET, PUT and DELETE methods for this path by clicking on the X icon associated with each method.
This leaves the POST method. The POST method is typically used for submitting data, which is the purpose of your API.
Associate your API to a Service Archive file.
In z/OS Connect EE, a service archive file (.sar file) provides information about the underlying service, including its expected request and response JSON schemas.
Note: z/OS Connect EE provides tooling to generate .sar files for its compatible subsystems (including CICS®, IMS?, DB2®, and IBM® MQ).
In this scenario, the .sar
file is already generated, so you can focus on creating, deploying, and testing your API.
Click Service….
Click File System.
Browse to C:/Service Archive Files
.
Select the contacts.sar
file and click Open.
In the dialog box that opens, click OK to confirm the import.
Click OK.
The contacts
service is now associated with the get method of your API.
contacts
service.
In this scenario, the connection between z/OS Connect EE and IMS is configured for you (using the IMS service provider).
The final step is to configure the mappings between your new API and the contacts
service, which represents the IMS program logic.
Map your API parameters to fields in the associated service.
contacts
service, and to remove redundant fields from the API documentation.
Next to the POST method, click Mapping… then click Open Request Mapping.
Expand the IVTNO_INPUT_MSG
section on the left side of the tab.
This shows fields that are exposed through the API and made available to the REST clients. By default, it is a one-to-one mapping to the fields that are exposed by the service unless you change the mapping.
IN_COMMAND
field on right side of the tab, in the service definition, then click Add Assign transform.Leave the Omit from interface option checked to exclude this value from the API documentation.
Note: This mapping defines the flow of a value, which is passed in by an API consumer, to the service associated with the API. The service then passes the value to the IMS program. At each stage, the data is transformed into formats and structures that each participant can understand.
Remove irrelevant values from the response so that your API returns relevant fields only.
The API you're creating is designed to pass back information about a requested item in the phone book program. However, the contacts
service contain several fields that aren?t relevant to that request.
You can safely remove these fields to make the API response and the API documentation clearer.
OUT_COMMAND
on the right side of the tab, and select Add Remove transform.This excludes this field from the body of the response.
You completed your API front end, your service association, and respective API-to-service mappings, so go ahead and make this API available.
Package and deploy your API from within the API Editor.
Deploying your API is a quick, simple process that you can complete without leaving the developer environment.
In the Project Explorer view, select your API project (phonebook) and right-click to select z/OS Connect EEDeploy API to z/OS Connect EE Server.
Optional: If the z/OS Connect EE server is disconnected, connect to the server by clicking on the red icon at the top of the Deploy API dialog.
You are now connected to the z/OS Connect EE server.
Click OK to deploy your API.
When the deployment completes, click OK in the Result dialog box.
Your API is now successfully deployed!
Test your API by using the built-in Swagger UI.
You can use the built-in Swagger UI to test out an API from within the developer environment. Let's try that now by opening up the Swagger UI for your new API, and adding a contact to the phone book.
In the z/OS Connect EE Servers view, expand the API folder, right-click your API, and click Open in Swagger UI.
In the tab that opens, click default, and then /contacts
The IMS program that you have exposed by creating this API contains contact information.
You can use your new API to add a new contact.
Click the Example Value box to copy the request message format into your phone book POST request.
Click Try it out!.
Information about the request URL, request headers, response body, response code, and response headers are provided. The response body contains the output message. The OUT_MESSAGE
would contain one of the following messages:
Congratulations! You've successfully exposed an IMS? application as a RESTful API by using z/OS Connect EE!