The document describes z/OS Connect Enterprise Edition V2.0, which provides a REST API gateway for accessing mainframe systems like CICS, IMS, and DB2. It improves upon prior versions by offering full support for REST standards, consistent Eclipse-based tooling, and the ability to define and package APIs using the Swagger 2.0 format to enable discovery and portability. The tooling allows developers to easily create and deploy mainframe APIs that can then be accessed by applications and services.

1. 1IBM
_
Chapter
Opening
September 16, 2015Presentation Title
Enabling Mainframe Assets for API Economy
with
z/OS Connect Enteprise Edition V2.0
XXXIII Konferencja Common
16 maja 2016
Hotel Narvil Conference & Spa
Maciej Zrobek
IBM Polska Sp. z o.o.
z Systems SW Technical Sales
maciej.zrobek@pl.ibm.com

2. 2IBM
_
Market trends and the API Economy
2
Enterprise
Applications
Enterprise
Data
Enterprise
Transaction
Processing
CICS
IMS
Batch
WAS
Systems of Record
Existing direct access: messaging, web services
Aggregating services
Enterprise
Systems
Integration

3. 3IBM
_
3
Enterprise
Applications
Enterprise
Data
Enterprise
Transaction
Processing
CICS
IMS
Batch
WAS
Systems of Record
Existing direct access: messaging, web services
Enterprise
Systems
Integration
Aggregating services
On-Premise Enterprise APIs
Cloud APIs
Mobile-Optimized APIs
Cloud-based
Services
Market trends and the API Economy

4. 4IBM
_
4
Enterprise
Applications
Enterprise
Data
Enterprise
Transaction
Processing
CICS
IMS
Batch
WAS
Systems of Record
Existing direct access: messaging, web services
Enterprise
Systems
Integration
Aggregating services
On-Premise Enterprise APIs
Cloud APIs
Mobile-Optimized APIs
Cloud-based
Services
Self-describing
Discovery
REST APIs
JSON payload
Open API
Market trends and the API Economy

5. 5 2016 © IBM Corporation5
Brief review of REST and JSON
GET
POST
PUT
DELETE
http://<host>:<port>/path?name=value&name=value
HTTP verbs are used to suggest
the action against the resource
Standard HTTP host and (optionally) port
designation
The "path" narrows the request to a "resource" (ex:
"accounts") on the target system
Parameters can be used to provide specific
values for the action against the resource
{
"First_Name": "John",
"Last_Name" : "Smith",
"Address" : "1234 Maple"
"City" : "Chicago"
"State" : "IL"
"ZIP" : "60601"
}
JSON:
A way to express name/value pair data
Used to carry data in a request (usually PUT or POST)
Used to provide data in a response
REST is increasingly popular as an integration pattern because it is stateless, relatively lightweight,
is relatively easy to program to, and operates well with discovery mechanisms such as IBM’s API
Management product.

6. 6 2016 © IBM Corporation6
Evolution of Mainframe Integration Patterns
Tight Integration
All components located on
mainframe, and linkages are
tightly coupled
Service Oriented
Loose coupling using
network-based protocols
such as SOAP/WSDL
Web Access
Screen-scraping of 3270
applications
Messaging
Using technologies such as
IBM MQ
API Economy
Integration based on a set of well-
understood and easily-accessible
APIs, increasingly based on
REST/JSON patterns
This is where z/OS Connect fits
into the picture
These earlier patterns are still in use
and in many cases are the best
pattern for the application. Just
because they came earlier, does not
mean they are now obsolete.

7. 7 2016 © IBM Corporation
Mid-Tier Function or Device
REST-handling and data conversion
handled in the mid-tier, and other
connectivity mechanism (SOAP/HTTP,
JCA, JMS, JDBC) used to connect to
backend.
REST
Function
Clients
CICS
IMS
MQ
DB2
Examples:
l DataPower
l IBM Integration Bus
l MobileFirst
l Other
Direct to z/OS Backend
REST-handling and data conversion
handled by each backend system
(such as CICS or IMS).
Examples:
l CICS JSON
web services
l IMS Mobile
Feature Pack
Clients
Backend
"Gateway" to the LPAR
REST-handling and data conversion
handled by a function on the LPAR, with
backend systems unchanged.
Examples:
l z/OS Connect V1.0
l z/OS Connect EE V2.0
Backend
Clients "Gateway"
CICS
IMS
MQ
DB2
Mid-Tier
This solution will often have mid-tier functions
Mid-Tier
This solution can have a mid-tier as well
Several Ways to Bring REST into Mainframe

8. 8 2016 © IBM Corporation
When to use good old CICS web services?
Consider using CICS web services when you want to:
• Reuse an existing CICS web services infrastructure
• Exploit the ability of web service pipeline for auditing or message transformation
• Exploit WS standards such as WS-Security
• Manage conversion of JSON messages to SOAP messages in an intermediary gateway
(rather than on the mainframe), for example, in an API gateway or an ESB
• Use outbound or inbound web services
8
CICS TS
CICS web
service pipeline
SOAP/
HTTP
CICS web
service pipeline
Service
provider
application
Service
requester
application
Service
requester
application
Client
Service provider
application
Endpoint

9. 9 2016 © IBM Corporation9
“Mainframe data smells different”
The misconception:
§ “Mainframe data is difficult to access”
§ “I want to discover my own services”
§ “I don’t want to be bound by formalised COBOL (or even XML!) data structures”
§ “Solution: let’s hold the data with easier access… maybe a cache/ noSQL DB?”
Certainly not true or necessary!
With technologies like z/OS Connect Enterprise Edition …
…contemporary developers can now consume mainframe services in precisely the
same way as a Google Maps or Facebook API

10. 10 2016 © IBM Corporation10
Integration solution Description Recommendation
z/OS Connect EE V2.0 Extends the support available with z/OS
Connect V1.
Includes tooling for API creation and
deployment.
Use to enable unified REST interface for CICS, IMS
and DB2.
Avoids multiple data transformations (use REST/JSON
as message format from the client to the mainframe).
Use to enable discovery of APIs
IBM API Connect Comprehensive API lifecycle to Create, Run,
Manage and Enforce APIs and Microservices.
DataPower and Node.js deployment options
Use to create APIs and microservices that consume z
Systems APIs
Manage and secure z System APIs created by z/OS
Connect
IBM DataPower Gateway SOA and mobile security gateway. Use for securing access to mainframe, and as runtime
for API Gateway.
Strategic REST API solutions
Create Run
ManageSecure

11. 11IBM
_
API-enabling z Systems: z/OS Connect Enterprise Edition
Mobile apps
Web
apps
Cloud /
Bluemix apps
REST API
consumers
z/OS Connect
Enterprise Edition
CICS
IMS
WAS
DB2*
MQ*
* Statement of Direction
The strategic REST API gateway for z Systems

12. 12 2016 © IBM Corporation12
z/OS Connect V1.0 – the first approach (available June 2014)
Data
Conversion
Discovery
Function
Audit
Function
Logging
Function
Granular
Authorization
CICS
IMS
DB2
Batch
WAS
REST
Client
REST
JSON
WebSphere Liberty
Profile z/OS
2
3
4 A long-running
task using
WOLA APIs to
host a service
z/OS
Connect
V1.0
1
1. z/OS Connect a “feature” of Liberty
2. “Service Provider” = backend connectivity
3. “Interceptors” = configurable function in
server.xml
4. Extensible interface = flexibility

13. 13 2016 © IBM Corporation13
z/OS Connect V1.0 was a good start but there was space for improvement …
Confusing Entitlement / Delivery
z/OS Connect was a no-charge feature entitled under
with WAS z/OS, CICS, IMS or DB2 license. Multi-
backend usage was different depending on
entitlement. Acquisition and installation was different
depending on entitlement.
Summary: entitlement and delivery model created
some confusion
Inconsistent Tooling Across Backends
The tooling support was a function of the entitlement
option used to acquire z/OS Connect V1. IMS and DB2
provided an Eclipse based tooling environment. CICS
employed CICS Explorer, but not to the degree IMS and
DB2 integrated z/OS Connect with tooling. WAS z/OS
relied on manual service definitions.
Summary: consistent tooling preferred
First Generation REST
z/OS Connect V1.0 REST implementation was
essentially an RPC model. Query parameters were
not accessible. Header information not accessible.
HTTP verb usage pattern not well-formed and
consistent.
Summary: more complete REST implementation
model was needed

14. 14 2016 © IBM Corporation14

15. 15 2016 © IBM Corporation15
z/OS Connect Enterprise Edition V2.0 (available Dec 2015)
Liberty z/OS
z/OS Connect EE
V2.0 Server
Backend Systems
(CICS, IMS, DB, etc.)
• IBM z/OS 2.1 or higher
• IBM 64-bit SDK for z/OS,
Java Technology Edition
V7.1.0 or V8.0.0
Eclipse
z/OS Connect EE
V2.0 Tooling
• Windows or Linux
• IBM CICS Explorer V5.3
• IBM IMS Explorer for Development V3.2
• IBM Explorer for z/OS Aqua V3.0
Runtime Server
• Same functionality as V1.0
• But now also hosts APIs
• Connects with backend system
• Liberty + z/OS Connect = “instance”
• You may have multiple instances
Tooling Platform
• Integrates with an Eclipse environment
• Define APIs
• Define data mapping
• Deploy APIs to runtime server
• Export API archive for other tools to deploy
1
2

16. 16 2016 © IBM Corporation16
Comparison of REST Support V2.0 vs. V1.0
z/OS Connect V1.0:
POST /accounts/create + (JSON with account create information)
POST /accounts/balance + (JSON with account number)
POST /accounts/update + (JSON with account number and deposit)
REST interface is very limited. It may be “good enough” for some use-cases, but it falls short of what many developers seek
when creating REST APIs.
z/OS Connect V2.0:
POST /accounts?name=Fred + (JSON with Fred’s information)
GET /accounts?number=1234
PUT /accounts?number=1234 + (JSON with dollar amount of deposit)
HTTP Verb conveys the method
against the resources; i.e., POST is for
create, GET is for balance, etc.
URI conveys the resource to be
acted upon; i.e., Fred’s account
with number 1234
The JSON body carries the specific
data for the action (verb) against the
resource (URI)

17. 17 2016 © IBM Corporation17
Comparing z/OS Connect V1 and V2
Function z/OS Connect V1.0 z/OS Connect Enterprise Edition V2.0
Support for REST Architecture Partial Full
Full mapping for GET, PUT, POST and DELETE
to backend services
Standard Tooling No
Each subsystem offers its own tooling
Yes
Based on z/OS Explorer
Deployment model Complex/ Manual
Artifacts must be moved manually
between environments
Simple/ Package-based
New deployable packages for
lower risk deployment
Support for Swagger 2.0
Standard
No
Custom discovery and import
Yes
API-economy ready
z/OS Subsystems Supported CICS, IMS, DB2, WAS
(SOD:MQ)
CICS, IMS, WAS
(SOD:DB2 &MQ)
License restriction Yes
Only to z/OS subsystem being accessed
No
A V2.0 instance can be used with any subsystem
Licensing model (Free) Entitlement through
CICS, IMS, WAS for z/OS and DB2 for z/OS
Per instance licensing,
separately chargeable
Future enhancements No
Product is Stabilized (after Liberty 8557 level)
Yes
Continuous Delivery Model

18. 18 2016 © IBM Corporation18
Eclipse-based Tooling for z/OS Connect EE V2.0
Eclipse project view,
which is familiar to
developers who have
used Eclipse-tooling
for other development
projects
Access query
parameters from
the URI
Assign API
function based
on HTTP verb
Provide data
mapping
definitions to the
service
API projects can be
exported and
imported for
portability between
developers

19. 19 2016 © IBM Corporation19
Request Mapping Capabilities
The API mapping model adds a powerful abstraction layer between the API consumer and the underlying z/OS assets.
HTTP Request Fields
Backend Data
Structure
Mapping
Actions
• Mapping of HTTP headers, path parameters (URI templates), and query parameters to the fields in the request message JSON
body.
• Pass-through, redaction, or defaulting of fields in the request or response message JSON body.
• Mapping and defaulting of HTTP headers in the HTTP response message.

20. 20 2016 © IBM Corporation20
Service Archive (SAR) -- Service Packaging
z/OS Connect V1.0
Service definitions in server
configuration file
(or in related side files)
Discovery function returned JSON
with services, but:
• Not Swagger definition
• Only service URIs, but did not contain
information about connectivity to
backend
Portability of service limited:
• No good “export” of service from a
hosting server
• Import into tooling largely a manual
process
server.xml
Deploy
Consume
Provides a standardized
method for defining, transporting and deploying
services
More flexibility and greater productivity
Better model from V1.0’s service definitions
Service Archive (SAR) File
• ZIP-format file
• Contains Swagger documentation of service
• Contains information about backend connectivity
• Produced by tooling
• Exportable to server runtime | Consumable by tooling

21. 21 2016 © IBM Corporation21
Discoverable APIs with Swagger 2.0
z/OS Connect EE V2.0
Server Instance
Swagger
2.0
/API_one
/API_two
:
/API_99
Configured APIs
Any Swagger-
compatible function
or device
Swagger UI
Function
“Standard*”
Swagger API
description
document
The inclusion of Swagger 2.0 support in z/OS Connect EE V2.0
makes exchange of API information standardized, which provides
compatibility with a wider set of devices and functions
* An emerging accepted industry standard, but not an official open standard
z/OS Connect
EE V2.0
Tooling
Tooling also produces
Swagger 2.0 for use by
z/OS Connect EE 2
Runtime environment
Client developers

22. 22 2016 © IBM Corporation22
Eclipse-based Tooling for z/OS Connect EE V2.0 – the full picture
POST
GET
PUT
DELETE
4. Discover API5.Invoke API
z/OS Connect EE V2.0
CICS
IMS
DB2 1
Interceptors
API Packages
3. Deploy API
(.aar)
REST client
API
mapping
model
1. Import
service
archive
(.sar)
z/OS Connect EE API editor
SWAGGER 2.0 description
2. Create API
1 per ENUS215-493 Statement of Direction

23. 23 2016 © IBM Corporation23
How to produce an SAR file – a CICS example
baqls2js
Request COPYBOOK
Response COPYBOOK
JCL
PARMS for baqls2js
BIND Files
These are binary-format files that contain information
about the field definitions and the data transformation
requirements.
JSON Schema Files
These provide the JSON schema used to interact with the
backend program based on the COPYBOOK data
requirements.
Service Archive (SAR) File
This is a ZIP-format file that contains the JSON schema and
some meta-data. This is input to the API Editor (next unit)
to create the APIs.

24. 24 2016 © IBM Corporation24
Achieving a Highly Available Environment
z/OS Connect EE V2.0
Server Instance
Backend Systems
(CICS, IMS, etc.)
z/OS Connect EE V2.0
Server Instance
z/OS Connect EE V2.0
Server Instance
Backend Systems
(CICS, IMS, etc.)
z/OS Connect EE V2.0
Server Instance
LPARLPAR
z/OS Connect EE V2.0 instances can be
duplicate
• On same LPAR
• Across LPARs
Because REST is stateless, network
routing functions can be placed in front
of duplicated instances and balance
traffic
Requests
Router, DataPower, API-M
Gateway, Sysplex Distributor, etc.

25. 25 2016 © IBM Corporation25
Example 1 - Multiple Backend Systems
z/OS Connect EE V2.0
Server Instance
CICS
Region A
CICS
Region B
IMS
Region X
API System
--------------------
/Banking CICS A
/Mortgage CICS B
/Cards CICS B
/Commercial IMS X
API
Consumers
z/OS Connect EE V2.0 becomes the REST API entry point to the LPAR for access to several backend
systems where the data program resides
Duplicate the z/OS Connect EE V2.0 instance for greater availability and/or greater throughput

26. 26 2016 © IBM Corporation26
Overview of z/OS Connect interceptors
Backend
Program
Request
Respons
e
Interceptor A
Interceptor B
Interceptor A
Interceptor B
The interceptor framework provides a way to call code to do pre-invoke work and then again to do post-invoke work:
In server.xml you can:
• Define ‘global interceptors,’ which apply to all configured
services
• Define interceptors specific to a given configured service
• Have services ‘opt out’ of global interceptors
z/OS Connect comes with an authorization interceptor (which user can access which service or API) and an audit interceptor
(for SMF recording)
It is also possible to write your own interceptor and have it called as part of request/response processing

27. 27 2016 © IBM Corporation27
Authorization interceptor
The “authorization interceptor” is a supplied piece of interceptor code that will check to see if the user has the authority to perform the action
requested:
Allowed to
Enter?
Administrator
Full authority
Operator
Start, Stop, etc.
Invoke
Invoke service only
“Fred” Yes
No
Go Away
Controlled by a
defined “role”
What the interceptor provides

28. 28 2016 © IBM Corporation28
Audit (SMF) Interceptor
The audit interceptor writes SMF 120.11 records with the following information captured:
Liberty Profile z/OS
z/OS
Connect
• System Name
• Sysplex Name
• Job Name
• Job Prefix
• Address Space Stoken
• Arrival Time
• Completion Time
• Target URI
• Input JSON Length
• Response JSON Length
• Method Name
• Service Name
• Userid
• Grouping Name
Server Identification Section
z/OS Connect User Data Section

29. 29 2016 © IBM Corporation29
z/OS Connect EE: Statements of Direction
IBM makes the following statements of general direction:
• IBM intends to deliver IBM z/OS Connect Enterprise Edition (EE) components and technologies through
continuous delivery of new features in the coming months.
• IBM intends that a future release of IBM CICS Transaction Server for z/OS (CICS TS) will provide
support for z/OS Connect EE to enable it to execute embedded within CICS TS.
• IBM intends that a future release of IBM MQ for z/OS will provide support for both z/OS Connect and
z/OS Connect EE.
• IBM intends to update IBM System Automation for z/OS V3.5.0 to deliver a new sample policy to allow
automated operations and restart of z/OS Connect and z/OS Connect EE.
• IBM intends that a future release of IBM IMS Enterprise Suite will provide support for z/OS Connect
EE.
• IBM intends to offer IBM DB2 for z/OS Version 11, or later, with support for the external interface
delivered in z/OS Connect EE V2.0, and DB2 RESTful API support that is fully integrated into the DB2
for z/OS Distributed Data Facility.
IBM's statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM's sole discretion. Information
regarding potential future products is intended to outline our general product direction and it should not be relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment, promise, or legal obligation to deliver any material, code, or
functionality. Information about potential future products may not be incorporated into any contract. The development, release, and timing of any future
features or functionality described for our products remain at our sole discretion.

30. 30 2016 © IBM Corporation30
CICS deployment options for z/OS Connect
Liberty z/OS
z/OS
Connect EE
V2.0 Server
Backend
Systems
(CICS, IMS, DB,
etc.)
CICS TS 5.2 or 5.31
z/OS
Connect EE
V2.0 Server
COBOL
• Unified REST/JSON access to different
backend systems
• Lightweight WebSphere Liberty
environment
• Uses optimized local connections (WOLA)
• Minimal changes to CICS system
• Direct calls to CICS COBOL programs
using JCICS
• Avoids need to setup WOLA
• Fewer things can go wrong
• HA and workload management is simpler
• Reuses web services pipeline
framework
• Native parsing support
1 per ENUS215-493 Statement of Direction

31. 31 2016 © IBM Corporation31
Integration solution Description Recommendation
z/OS Connect EE V2.0 Extends the support available with z/OS
Connect V1.
Includes tooling for API creation and
deployment.
Use to enable unified REST interface for CICS, IMS
and DB2.
Avoids multiple data transformations (use REST/JSON
as message format from the client to the mainframe).
Use to enable discovery of APIs
IBM API Connect Comprehensive API lifecycle to Create, Run,
Manage and Enforce APIs and Microservices.
DataPower and Node.js deployment options
Use to create APIs and microservices that consume z
Systems APIs
Manage and secure z System APIs created by z/OS
Connect
IBM DataPower Gateway SOA and mobile security gateway. Use for securing access to mainframe, and as runtime
for API Gateway.
Strategic REST API solutions
Create Run
ManageSecure

32. 32 2016 © IBM Corporation32
API Connect: Simplified & Comprehensive API foundation
What is API Connect?
An integrated creation, runtime, management, and security foundation for enterprise
grade API’s and Microservices to power modern digital applications
What does API Connect provide?
• Automated, visual and coding options for creating APIs
• Node.js and Java support for creating Microservices
• Integrated enterprise grade clustering, management and security for Node.js and
Java
• Lifecycle and governance for APIs, Products and Plans
• Access control over API’s, API Plans and API Products
• Advanced API usage analytics
• Customizable, self service developer portal for publishing APIs
• Policy enforcement, security and control
Create Run
ManageSecure

33. 33 2016 © IBM Corporation33
Where does API Connect fit?
External
App
Developer
Internal App
Developer
Partner App
Developer
Business
Partner Apps
Mobile &
Web Apps
Enterprise
Internal Apps
Internet of
Things
Manage
API Discovery
API, Plan, Product, Policy Creation
API, Plan, Product Version & Lifecycle
Management
Self-service App Developer Portal
API Monitoring & Analytics
Subscription & Community
Management
Secure
API Policy Enforcement
Enterprise Security
Traffic control & mediation
Workload optimization
Monitoring/Analytics Collection
Create & Run
(Node / Java)
Develop & Compose
Microservices
Connect Microservices to data
sources
Build, deploy, scale Microservices
Monitor & debug Microservices
Unified Node & Java Runtime
Mgmt
API Gateway
z System / Legacy Apps
Cloud Service
Application Server
ESB / Middleware
Data Store
APICmanagedMicroservicesTraffic
API Traffic
Consumer
(Systems of Engagement)
Provider
(Systems of Record)

34. 34 2016 © IBM Corporation34
API Connect with z/OS Connect
IMS
CICS
Systems of Record
Services on
Services on
• Discover z/OS Connect REST APIs
• Secure access to z/OS Connect REST APIs
• Provide self-service & social experience to API consumers on a built-in developer portal
• Enforce runtime rate limits, and throttle impact to z/OS systems
• Manage API subscribers with API lifecycle & Analyze API usage
Systems of Engagement
Management
+
Runtime gateway enforcement
Developer portal
API analytics

35. 35 2016 © IBM Corporation35
Summary
z/OS Connect is a mechanism that provides a REST interface platform to
z/OS as a Systems of Record.
z/OS Connect V1 was a no-charge feature; it was adequate for some use-
bases but for others key functional enhancement were needed.
z/OS Connect EE V2.0 is a separately orderable product from IBM that
provides those enhancements:
• More sophisticated handling of REST URIs patterns
• More sophisticated workstation tooling for API creation
• Inclusion of Swagger 2.0 for wider publication of API descriptions
• APIs as exportable artifacts for better deployment management

36. 36 2016 © IBM Corporation36
Want to Learn More?
z/OS Connect EE V2.0 announcement letter
Link here
z/OS Connect EE V2.0 web page
Link here
API Management web page
Link here
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

37. Lorem Ipsum dolor sit, to
amet consectetur irare a
adispicing elit done et
ectals tempus.
Quote
“ “
Author, Secondary Information
September 16, 2015Presentation Title
Thank you!!
37