architecture options for rest api enabling cics...

IBM Client Center Montpellier

Architecture options for REST API enabling CICS applications Nigel WilliamsIBM France

2/11/2016 Session GF


• Introduction– Review of REST , JSON etc.

• Options for create REST APIs with CICS

• Summary

• More information

Agenda


APIs are everywhere


GETPOSTPUTDELETE

http://<host>:<port>/path/{parameter}?name=value&name=value

Today APIs are being built on REST and JSON

HTTP verbs are used to suggest the action against the resource

The “path” narrows the request to a “resource” (ex: “accounts”) on a target system

Path‐parameters link to the resource

Standard HTTP host and (optionally) port designation

Query‐parameter can be used to provide specifics values for the action against the resource

https://maps.googleapis.com/maps/api/geocode/json?latlng=43.6144322,3.9071322


GETPOSTPUTDELETE

http://<host>:<port>/path/{parameter}?name=value&name=value

Example of a banking API

HTTP verbs are used to suggest the action against the resource

The “path” narrows the request to a “resource” (ex: “accounts”) on a target system

Path‐parameters link to the resource

Standard HTTP host and (optionally) port designation

Query‐parameter can be used to provide specifics values for the action against the resource

GET https://mybank.com/myBank/accounts/{accountId}Response {

"operation": “Balance Inquiry",{"date": "9/27/2016","amount": 1267.28,"account_name": "Mr or Mrs Smith"

} }


Relatively Lightweight

Compared to other technologies (for example, SOAP/WSDL), the REST/JSON pattern is relatively light protocol and data model, which maps well to resource-limited devices.

Relatively Easy Development

Since the REST interface is so simple, developing the client involves very few things: an understanding of the URI requirements (path, parameters) and any JSON data schema.

Increasingly Common

REST/JSON is becoming more and more a de facto "standard" for exposing APIs and Microservices. As more adopt the integration pattern, the more others become interested.

StatelessREST is by definition a stateless protocol, which implies greater simplicity in topology design. There's no need to maintain, replicate or route based on state.

Ubiquitous Foundation

It's based on HTTP, which operates on TCP/IP, which is a ubiquitous networking topology.

Why REST/JSON is a Popular Integration Pattern


PSD2 (European Payment Services Directive 2)

PSD2


Example APIs

Get Account Balance (TPP -> ASP)

Get Account Statement (TPP -> ASP)

Account Statement Report (ASP -> TPP)

Josh

Bank BBank A Credit CardProvider

Josh

Bank BBank A Credit CardProvider

Third Party Provider

Today PSD2

Account information services (AIS)

• All requests are likely to be REST APIs with JSON payloads

• APIs are also required for payments and accountsubscriptions

IBM Client Center Montpellier99

• Emerging requirements – driven by mobile, cloud & web 2.0 – for…– RESTful APIs

– Discoverable and self‐describing

– Agnostic to the service‐providing technology

EnterpriseApplications

EnterpriseData

Enterprise Transaction Processing

CICSIMS

BatchWAS

Systems of Record

Existing direct access: messaging, connectors, web services

EnterpriseSystems

Integration

Aggregating services

On-Premise Enterprise APIs

Cloud APIs

Mobile APIs

Cloud-based Services ?

Consuming z services: requirements today


APP

Microservicecontainers

MicroService

Core ‘connector’ Core ‘connector’

APIs

Core Core

API

AppMicroService

MicroService

MicroService App

AppApp

Applications, Channels & Partners

App

API gatewayAPI API API

APPSystems ofRecord

APPIntegrationLayer

and/or

Service Facade MicroService

CTG/MQ/web services

API centric architecture


Options for create REST APIs with CICS

11


Mid‐Tier Function or DeviceREST‐handling and data conversion handled in the mid‐tier, and other connectivity mechanism (SOAP/HTTP, JCA, JMS, JDBC) used to connect to backend.

Mid‐tier serverClients

CICSIMSMQDB2

Examples:DataPower GatewayAPI GatewayIBM Integration BusMobileFirstWebSphere

Direct to CICSREST‐handling and data conversion handled by CICS

Examples:CICS JSON web servicesz/OS Connect EE for CICSEXEC CICS TRANSFORM JSONTODATA

ClientsCICS

"Gateway" to the LPARREST‐handling and data conversion handled by a function on the LPAR, with backend systems unchanged.

Examples:z/OS Connect EE CICS TG

CICS

Clients "Gateway"

CICSIMSMQDB2

Mid‐Tier

This solution will often also have mid‐tier functions

Mid‐Tier

This solution can also have mid‐tier functions

Several Ways to support REST/JSON with CICS

Mid‐tier functions

12

REST API or service endpoint


CICS REST/JSON – first solutions to consider

Solution Products

Direct to CICSz/OS Connect EE for CICS z/OS Connect EE

CICS V5.2 APAR PI59303CICS V5.3 APAR PI54263

CICS Java application using JAX-RS running in Liberty JVM server CICS TS 5.1 and later

CICS non-Java JSON service provider CICS TS V5.3

Gateway to the LPARz/OS Connect EE z/OS Connect EE


CICS REST/JSON – other solutions that can be considered

Solution Products

Mid-Tier Function or DeviceCICS Web services CICS TS V3.1 and later

Direct to CICSCICS Mobile Feature Pack CICS TS V4.2

CICS JSON web services (Java solution with Axis2) CICS TS V5.2 and later

z/OS Connect V1 for CICS Liberty featureCICS TS V5.2 and later

EXEC CICS TRANSFORM JSONTODATA and DATATOJSON CICS TS V5.3 (APAR PI54841)

Gateway to the LPARz/OS Connect V1 (WOLA connectivity to CICS) Liberty feature

CICS TG JSON web services support CICS TG V9.1 and later


CICS

IMS

DB2*

MQ*

WAS

RESTful APIs available from one endpoint

With sophisticated mapping of true RESTful APIs to existing

mainframe services and data

ibm.biz/zosconnectdcDiscovery using OpenAPI

(aka Swagger)

z/OS Connect Enterprise Edition

* Statements regarding IBM future direction and intent are subject to change or withdrawal, and represent goals and objectives only.

1 per ENUS215‐493 Statement of Direction


5.Invoke APIz/OS Connect EE V2.0 CICS

IMS

DB2 1

Interceptors

API Packages

3. Deploy API

API mappingmodel

POST

GET

PUT

DELETE

REST client

1. Create service archive

SWAGGER 2.0 description

Steps to create an API

2. Create API

1 per ENUS215‐493 Statement of Direction

z/OS Connect EE API editor

4. Discover APIMQ 1


z/OS Connect EE V2.0API Editor

IBM CICS Explorer V5.3IBM IMS Explorer for Development V3.2IBM Explorer for z/OS Aqua V3.0

Compose the API URI path

Select the HTTP verb, and map the call to the underlying service

Use the "Mapping" function to assign static values, remove fields from client view, or move values to a field

The API Editor is what gives you the ability to define the specifics of your API.

1

3

2

The z/OS Connect EE V2.0 API Editor


Example ‘catalog’ API z/OS

CICS

z/OS Connect EE V2.0

https/json

GET /items?startItemIDGET /items/{itemID}POST /orders

Services

API

inquireCataloginquireSingleplaceOrder

GET /items?startItemID=<value>

GET /items/{itemID}

POST /orders + (JSON with item reference and quantity)

HTTP Verb conveys the method against the

resources; i.e., POST is for create order, GET is for

retrieving information about items in the catalog

URI conveys the resource to be acted

upon; i.e., item reference

The JSON body carries the specific data for the action (verb) against the

resource (URI)

Inquire item

Place Order

DFH0XCMN

Inquire Catalog

Items

Sample API response


When to use z/OS Connect EE V2.0?

Considerations for using z/OS Connect EE V2.0:

• Provide intuitive, workstation-based tooling that enables a developer to create RESTful APIs from traditional z/OS based assets

• Support the discovery of defined APIs using the Swagger 2.0 standard to share API descriptions

• Simplify REST service development process by making mainframe application owner responsible for API creation

• Manage API access control using SAF and audit access to SMF• Minimal changes to CICS

z/OS Connect EE V2.0 Server Instance

CICSRegion A

CICSRegion B

IMSRegion X

API System--------------------/Banking CICS A/Mortgage CICS B/Cards CICS B/Commercial IMS X

API Consumers

19

RESTfulJSON


How z/OS Connect EE for CICS works

For CICS to provide a service from an external JSON client:• It receives the request into a z/OS Connect EE• Transforms the JSON message (Java or non-Java based on pipeline definition)• Passes it to the target application program

The JSON response is generated and returned to the JSON client 22


When to use z/OS Connect EE for CICS?

Considerations for using z/OS Connect EE for CICS: • Same benefits as z/OS Connect EE in standalone mode e.g API Editor and Swagger support• Manage API access control using SAF and audit access to SMF• Simplify CICS REST service development process by making CICS application owner

responsible for API creation• Local JCICS call • Integrates with CICS pipeline processing and CICS tools (CPSM, CICS Explorer…)• Option to use non-Java JSON data transformation (CICS TS V5.3 only)

Liberty JVM server

z/OS Connect

EE

CICS program

Interceptors

CICS Provider

Data Transform

RESTJSON

server.xml

CICS TS

24


• If you want to parse the JSON by using Java within the Liberty JVM server, insert the following XML into your pipeline configuration file:<?xml version="1.0" encoding="EBCDIC-CP-US"?> <provider_pipeline_json

xmlns="http://www.ibm.com/software/htp/cics/pipeline"> <jvmserver>LIBERTY</jvmserver>

</provider_pipeline_json>

• If you want to parse the JSON by using the non‐Java parser, insert the following XML into your pipeline configuration file:<?xml version="1.0" encoding="EBCDIC-CP-US"?> <provider_pipeline_json java_parser="NO"

xmlns="http://www.ibm.com/software/htp/cics/pipeline"> <jvmserver>LIBERTY</jvmserver>

</provider_pipeline_json>

JSON parsing options

25


1,48

1,78

0,0

0,2

0,4

0,6

0,8

1,0

1,2

1,4

1,6

1,8

2,0

Native Java

CPU

cos

t per

requ

est (

ms)

Parser implementation

zIIP-eligible

non-eligible

Comparing Java and native parsers for a medium‐sized request and response

27

Note: Data taken from test with z/OS Connect for CICS published in “CICS TS for z/OS V5 Performance Report”


13,31

18,62

0

2

4

6

8

10

12

14

16

18

20

Native Java

CPU

cos

t per

requ

est (

ms)

Parser implementation

zIIP-eligible

non-eligible

Comparing Java and native parsers for 64 KB request with 32‐byte response

30


When to use CICS non-Java JSON service provider?

Considerations for using non-Java JSON service provider:

• Complete non-Java solution• Only basic REST/JSON support (e.g no API Editor)• Can have performance benefits for large request and/or response messages• None of the processing is eligible for offloading onto zIIP

33

Non-java pipeline CICS

program

Terminal handler

Data Transform

RESTJSON

CICS TS V5.3

Message handlers


CICS Liberty support

34

What can I do with Liberty in CICS?• Porting Java EE application to CICS• New integration logic for existing CICS services

o RESTful services, SOAP Web services, Servlet, JSP• Java business logic in CICS


When to use Java applications in a Liberty JVM server?

Considerations for using Java applications in CICS Liberty:• Have complete control over the application interface (JSON or XML)• Develop Java integration logic that reuses existing CICS or Java components• Exploit Java frameworks to handle complex data transformations• Use outbound or inbound services

35

Liberty JVM server

Java programJAX-RS JAX-WS

CICS program

SOAP

CICS TS V5.1 or later

Bespoke Data Transform

RESTfulJSON


CICS

VSAM File (EXMPCAT)

Inquiry itemInquire Catalog

Place Order

Example java wrapper program

CatalogManagerusing JAX‐RS, JZOS and JCICS

https/json

WebSphere Liberty

DFH0XCMN

GET /items?count=20&startItemID=50&orderBy=cost

GET /items/50

POST /orders + (JSON with item reference and quantity)

36


Implementation steps

1. Use the JZOS Record Generator to create Java record wrapper class from COBOL structure• The IBM JZOS Batch Toolkit for z/OS SDK is a set of tools

designed to help integrate Java applications with z/OS services• Provides a record class generator which imports COBOL

copybooks or Assembler DSECTs and generates helper classes to marshal data to and from the record structure

2. Develop CICS Java program to implement the REST service interface using JAX-RS and use the record wrapper and JCICS to call COBOL program

3. Deploy Java application into a CICS Liberty server

37


Java RecordClassGenerator

utility jzos_recgen.jar //JZOS EXEC PGM=BPXBATCH

//STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //STDPARM DD * SH /usr/lpp/java/J8.0_64/bin/java -cp /u/ephan/jzos_recgen.jar com.ibm.jzos.recordgen.cobol.RecordClassGeneratoradataFile="//'EPHAN.CICS.COBADATA(DFH0XCMN)'" symbol=DFHCOMMAREA outputDir=/u/ephan/ package=com.ibm.cics.catalogmanager.recordsclass=JZOSCatalogManagerCommarea;

/*

CICSTS.V5R3.CICS.SDFHSAM(DFH0XCMN)

// SET PROG='DFH0XCMN' //COBOL EXEC PGM=IGYCRCTL,REGION=200M, // PARM=(NODYNAM,RENT,LIST,MAP,XREF,ADATA, // 'CICS(''SP,COBOL3'')') //STEPLIB DD DSN=COBOL.V6R1.SIGYCOMP,DISP=SHR // DD DSN=CICSTS.V5R3.CICS.SDFHLOAD,DISP=SHR //SYSLIB DD DSN=CICSTS.V5R3.CICS.SDFHCOB,DISP=SHR // DD DSN=CICSTS.V5R3.CICS.SDFHMAC,DISP=SHR // DD DSN=CICSTS.V5R3.CICS.SDFHSAMP,DISP=SHR //SYSADATA DD DSN=EPHAN.CICS.COBADATA(&PROG), // DCB=(RECFM=VB,LRECL=1020,BLKSIZE=1024), // DISP=(NEW,CATLG),SPACE=(CYL,(3,3,10)) //SYSPRINT DD SYSOUT=A //SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS), // UNIT=SYSDA,SPACE=(TRK,(3,3)) //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) …//SYSIN DD DSN=CICSTS.V5R3.CICS.SDFHSAMP(&PROG),DISP=SHR//

1. Create record class Compile COBOL program to create ADATA

EPHAN.CICS.COBADATA(DFH0XCMN)

/u/ephan/com/ibm/cics/catalogmanager/records/ Type Filename _ Dir . _ Dir .. _ File JZOSCatalogManagerCommarea.java

Building Java record class

38


2. Develop CICS Java program

Liberty JVM server libraries for CICS TS 5.3

HTTP RequestJZOSCatalogManagerCommarea classgenerated by jzos_recgen.jar

Create a Dynamic Web Project

CatalogManagerService classservlet using JAX-RS to process the HTTP requests

CatalogManagerImpl classsends data to CICS programsusing JCICS

ibmjzos.jar

ItemData & OrderDatarepresent data models

39


3. Deploy Java application

a. Create a CICS bundle project in Eclipse using the menu New -> CICS Bundle Project • Add the Dynamic web project CatalogManagerService

b. Deploy to zFS using the menu Export Bundle Project to z/OS UNIX File System

c. Create a CICS BUNDLE definition referencing this zFS location and install the bundle

d. Test the application using a REST client

40


Summary

41

Client type Solution Comments

REST

z/OS Connect EE V2.0 based REST APIs

RESTful interface (with API Editor) Seperately priced feature (at V2.0)Discovery of z/OS assets leveraging Swagger 2.0Option to use non-Java JSON data transformation (CICS TS V5.3 only)

Liberty JAXRS Java solution supported with Liberty in CICS TS V5.1Inbound and outbound support

Non-Java JSON service provider Reuses same framework as CICS SOAP web services. Completely non-Java solution

Liberty JVMz/OS

Connect

Other channels

Web

MobileJSON/REST

JSON/REST

API Gateway

JSONWeb services

Primary options for deploying CICS REST APIs

42


More information

z/OS Connect EE V2.0 Getting Started Guide – Step by step guide to install z/OS Connect

EE and create APIs, available here– API created from CICS Catalog Manager

application– Eclipse project provided to customers with

guide

43

Redpaper– Provides guidance on choosing between

solutions, available here– Contains customer scenarios– Planned to be updated 1Q2017


More information

44

Redpaper– Provides guidance on choosing between

solutions, available here– Contains customer scenarios– Planned to be updated 1Q2017

z/OS Connect EE V2.0 Development Center

– Cental site for z/OS Connect information, available here

– Download open beta and tooling– Articles to help you get started


More information (cont…) CICS Developer Center– Java in CICS– Getting started with CICS Java– Developing Applications– Managing the Java environment

Other resources• IBM Redbook - IBM CICS and Liberty: What

You Need to Know• JZOS for z/OS SDKs – Cookbook• IBM Redbook – Java Stand-alone Applications

on z/OS Volume II• EDUPGM sample on CICSDev – GitHub• JZOS Record Generator – Download

45

Session feedback

• Please submit your feedback at

http://conferences.gse.org.uk/2016/feedback/nn

• Session is GF


Backup charts

47


Integration architectures

Integration architectures Description When to useREST Resource-oriented architecture

based on HTTP URL and verbs, and JSON.

De facto standard for mobile, web, and cloud applications.JSON payloads are less brittle to application changes.

Web services Service-oriented architecture based on standards like SOAP, XML, and Web services (WS.*) specifications.

Use when solution requires application integration between different service types and platforms, and XML is the predominant data payload.

APIs and API management Architecture for creating, assembling, managing, securing, and socializing web APIs.

Use when business functions need to be discoverable and need a high degree of operational governance.

Messaging Asynchronous transport mechanism.

Use when two applications are not necessarily available at the same time. Exploit for MQTT, for publish/subscribe applications, or when reusing existing messaging infrastructure.Use when assured delivery is required.


CICS Integration solutions

49

Integration solution Description When to usez/OS Connect Enterprise Edition IBM’s strategic REST gateway

into mainframe subsystemsUse when discoverable REST/JSON APIs are required for access to CICS, IMS, WAS, DB2 on z/OS.

CICS web services CICS solution for SOAP/XML service enablement

First considerationfor web service enabling CICSapplications, particularlywhen you need to supportmultiple service requestertypes or need bi-directionalsupport.

CICS Transaction Gateway Set of client and server softwarecomponents that allow a remote client application to invoke programs in a CICS region.

Most appropriate solutionwhen service requester isJEE component and whenhigh QoS required (highavailability, transactions,security).

IBM MQ IBM’s asynchronous messaging solution.

Use for reliable once, and once only, assured delivery for asynchronous and pseudo-synchronous connectivity.

architecture options for rest api enabling cics...

Documents