Make Your API Catalog Essential with z/OS Connect EE

PZS-3111: Make Your API Catalog
Essential with z/OS Connect EE
Drive new business opportunities through naturally
RESTful APIs and JSON
Ted Cipresso, IBM Silicon Valley Lab
Rob Jones, IBM Hursley Lab

Swagger-defined REST APIs
Introduction to Swagger and related tools

Swagger Specification and Tools (swagger.io)
Swagger Editor
An editor for designing Swagger
specifications from scratch,
using a simple YAML structure.
Swagger UI
Use a Swagger specification to
drive your API documentation.
SDK Generators
Turn an API spec into client
SDKs or server-side code with
Swagger Codegen.
3

Swagger Editor – Develop an API Specification
Swagger Editor
Swagger UI
SDK Generators
Swagger Codegen.
4

The Swagger Editor can be
used to the browse and
validate the design of an API.
5

6
Swagger for an API can be
loaded directly from a server
into the Swagger Editor

Swagger UI – “Try out” an API
Swagger Editor
Swagger UI
SDK Generators
Swagger Codegen.
7

8
loaded directly from a server
into Swagger UI

9
Swagger UI can be used
to unit test methods
offered by the API.
Swagger Editor may also
be used for unit testing,
however it requires
Node.js whereas Swagger
UI does not.

10
The POST method did not
require a request body,
rather all of the input data
is carried on the URI.
This is typical of REST APIs.

SDK Generators – Integrate or Implement an API
Swagger Editor
Swagger UI
SDK Generators
Swagger Codegen.
11

Choice of REST API Specifications
• While Swagger is the “most popular” specification, API developers may
choose from other specifications to document REST APIs:
– API Blueprint
– RAML
– Slate
– WADL
• To address proliferation of specifications,
tools such as API Transformer help by
converting between specification types.
• Swagger’s SDK is a strong selling point.
12

Introducing IBM z/OS Connect
Enterprise Edition V2.0
Product key points and RESTful reminder

APImanagement
DataPower
14
External API
consumers
External API
consumers
Enterprise API providers
IBM z/OS Connect Enterprise Edition
40,000ft Enterprise API ecosystem view
z Systems
POWER
Intel
Public cloud
Linux
Workloadbalancing
Firewall
Standard network
mediation layers
HTTP/JSON
transport +
dataInternal API
consumers
Internal API
consumers
APIs described by
SWAGGER
Mixed assets,
discoverable as
self-describing
REST interfaces

REST API
consumers
REST API
consumers
z/OS
Create and deliver natural REST
APIs for z Systems assets in a
unified manner across z/OS
subsystems with integrated
auditing, security and scalability
API
Management
Mobile apps
Web apps
1
see ENUS215-493
Statements of Direction
10,000ft conceptual view
Business partner
applications
Internal
applications
15

Liberty z/OS
z/OS Connect EE
server instance
SoR subsystems
CICS, IMS, WAS,
DB2, MQ, …
IBM 64-bit SDK for z/OS,
Java Technology Edition
V7.1.0 or V8.0.0
z/OS Explorer Aqua V3.0
z/OS Connect EE
API Editor
Windows, Linux or OS/X with
•IBM CICS Explorer V5.3
•IBM IMS Explorer for Development V3.2
•IBM Explorer for z/OS Aqua V3.0
Runtime Server
•Includes service capabilities of V1.0
•Adds the ability to hosts APIs
•Integrates with multiple z subsystems
•Liberty + z/OS Connect = “instance”
•You may have multiple instances
Tooling Platform
•Integrates with an Eclipse 4.4 environments
•Defines APIs and generates SWAGGER 2.0
•Compose API mapping models
•Deploy APIs to runtime server
•Export API archive for other tools to deploy
1
2
Two parts to every story
16

API consumers, API packages, mapping and transformation, description, discovery and invocation!
Consumer view z/OS Connect EE V2 SoR
z-asset APOST
z-asset BGET
z-asset CPUT
z-asset DDELETE
API package
Create-service
Read-service
Update-service
Delete-service
/myapi/resource/{id}
HTTP
Headers
+
JSON
Discover APIs
with SWAGGER
description
Consumers can use SWAGGER
to generate API client code
Service
archive SoR-specific
utilities
containing
e.g. CICS
WSBind, IMS
meta-data
Export API
z/OS Connect EE API editorz/OS Connect EE API editor
JSON /
SoR
xforms
(.sar)
(.aar)
Import
17

18
z/OS Connect
dedicated Liberty
z/OS Connect
product
feature V2.0
service
provider
features
WOLA
API composition
tooling for Eclipse
REST
client
API deployment
scriptable interface
WOLA service provider is included
as a Liberty feature in the
z/OS Connect EE product (+ the
base WOLA feature)
REST client service provider
allows integration of REST services,
using z/OS Connect as a proxy
Angel The Liberty angel runtime is
included with z/OS Connect EE
Provides authorized services
Create API packages
and iteratively deploy
for testing
Automate deployment
of API packages with
target-specific
customizations
SMF89
registration &
usage records
Runtime component view – what comes in the box

19
z/OS Connect
dedicated Liberty
z/OS Connect
product
feature V2.0
service
provider
features
WOLA
API composition
tooling for Eclipse
REST
client
API deployment
scriptable interface
WOLA service provider
REST client service provider
Angel The Liberty angel runtime is
included with z/OS Connect EE
Provides authorized services
Create API packages
and iteratively deploy
for testing
Automate deployment
of API packages with
target-specific
customizations
SMF89
registration &
usage records
Extra
SPs
CICS, MQ, DB2 plan to ship
further service provider
implementations for deployment
with z/OS Connect EE
IMS Enterprise Suite 3.2.1
includes IMS Mobile Feature
Pack for z/OS Connect
Enterprise Edition
Runtime component view – extending z/OS Connect EE

POST /accounts/create + (JSON with account create information)
POST /accounts/balance + (JSON with account number)
POST /accounts/update + (JSON with account number and deposit)
A collection of individual services
REST interface is very limited, HTTP method is NOT significant.
“Good enough” for some use-cases, but falls short the expectations of REST API consumers.
A naturally RESTful API
/accounts?name=Fred + (JSON with Fred’s information)
/accounts?number=1234
/accounts?number=1234 + (JSON with dollar amount of deposit)
/accounts?number=1234
HTTP verb conveys the operation
against the resources; i.e., POST is
for create, GET is for balance, etc.
URI conveys the resource to
be operated upon; i.e., Fred’s
account with number 1234
The HTTP body encoded in JSON
carries the specific data resulting from the
action (verb) against the resource (URI)
Aligned with API consumer expectations for REST APIs
What’s in a URI ?
JSON-RPC style services vs. a “naturally RESTful” API
POST
GET
PUT
DELETE
20

CICS Catalog Manager: sample API mapping model
VSAM File (EXMPCAT)
CICS
Inquire item
Place Order
z/OS Connect EE V2.0
https/json
API HTTP
verb
URL
List catalog GET https://zt01.pssc.mop.fr.ibm.com:50743/catalogManager/items?startItemID
Get details of
item
GET https://zt01.pssc.mop.fr.ibm.com:50743/catalogManager/items/{itemID}
Order item POST https://zt01.pssc.mop.fr.ibm.com:50743/catalogManager/orders
DFH0XCMN
GET or POST
Inquire Catalog
GET /items?startItemID
GET /items/{itemID}
POST /orders
Services
catalog API
inquireCatalog
inquireSingle
placeOrder
Designing an API for the CICS Catalog sample
A sample API mapping model
21

DFH0XCP3
Inquire Catalog
DFH0XCP4
Inquire Single
DFH0XCP5
Place Order
DFH0XCMN
CICS Programs
Service for Inquire Catalog
serviceName="inquireCatalog"
Service for Inquire Single
serviceName="inquireSingle"
Service for Place Order
serviceName="placeOrder"
WOLA Information
registerName="CICSREG"
serviceName="DFH0XCMN"
Data transformation information
zosConnectDataXform
GET
/items?startItemID=<value>
GET
/items/{itemID}
POST
/orders
API Definition
Service Definitions 1
2
3
5
4
6
The API is generated using the z/OS
Connect EE V2.0 API Editor in Eclipse
1. CICS program named in WOLA
serviceName
2. CICS copybooks used to create data
transformation WSBIND files (JSON to
COMMAREA)
3. Service definitions
4. CICS region named in WOLA
registerName
5. WOLA DataXform specifies location of
WSBIND files
6. API we want to construct with the API
Editor
Designing an API
A sample API mapping built from CICS catalog sample services
22

z/OS Connect EE API Editor
API composition

Eclipse Tools for Mainframe Development
Composite update site hosts compatible versions of Eclipse platforms & plugins
24
https://developer.ibm.com/mainframe
Release train delivering
compatible versions of
Eclipse platforms & plugins
for IBM tooling on z/OS.
https://developer.ibm.com/mainframe

Model and create natural REST APIs based on z/OS Connect services
25https://developer.ibm.com/mainframe/products/zosconnect

Create the paths and methods supported by your REST API
26
service to invoke
for this path and
method
unique mappings of
the service for this
path and method

Create unique RESTful mappings of z/OS Connect services per path and method
27
Map HTTP headers,
query parameters,
and path parameters,
to the service.
Map static
values to fields

Service
archive
SoR-specific
utilities
containing e.g.
CICS WSBind,
IMS meta-data
Import SAR files to
SoR-specific utilities for SAR generation
IMS Explorer for Development (shown)
•IMS Transaction data xforms
BAQJS2LS / BAQLS2JS utilities (supplied)
•CICS program data xforms
Ready for API composition….
Composing an API from service archives
28

API composition: start with service archives
29

API archive includes
generated SWAGGER 2.0
Upload the API archive to zFS and deploy
using the apideploy command
API composition: export API package as API archive (AAR)
30

API composition: Generated SWAGGER (shown in SWAGGER editor)
31

Demo
Create a Swagger-defined API using z/OS Connect

API Management
Secure, scale, manage, monitor, and socialize APIs

API Management
• APIs hosted on a zEE server are not “managed”, therefore an API
management (APIm) solution should be used.
• IBM APIm enhances zEE APIs with the following capabilities:
– Secure and scale
• manage access to APIs by using API keys and secret keys.
– Manage and monitor
• extract API usage and analytics data to quickly react to new opportunities.
– Administration portal
• self-registration, quotas, key management and security policies.
– Developer portal
• engage application developers and foster use of published APIs.
• customize with branding to advertise, market, socialize and sell APIs.
34

35
A zEE API can be imported
into APIm by referencing its
Swagger definition that is
hosted on the zEE server.

36
Provide the location of
the Swagger definition
on the zEE server.

37
The Swagger definition
is parsed and shown
for confirmation.

38
The zEE API is now
imported into APIm
and can be managed.

z/OS Connect EE pricing
Instance based pricing model

40
z/OS Connect EE introduces an innovative new pricing model
on z Systems.
“per instance” pricing metric
•Based upon the maximum number of active concurrent
address spaces
•Tiered usage bands
•provides increasing value as the size of an overall
deployment rises; low cost of entry for small projects
•Auditing is required through SMF89-2 records
•hourly snapshots of the number of concurrent instances,
reports created with utility IFAURP
What about pricing?
A new approach

41
Number of
Simultaneous Instances
VUs per Simultaneous Instance
1 to 4 1 VU per Simultaneous Instance
5 to 10 4 VUs + 0.6660 VUs per Simultaneous Instance > 4
>3000 36 VUs + 0.0007 VUs per Simultaneous Instance > 3000
What about pricing?
Value Unit exhibit VUE037 (see announcement letter ENUS215-493)

42
Measured Usage and S/390 Usage Pricing Charges Page 2
IFAURP 4.1.2 Software Product Registration Report 14 DECEMBER 2015
------------------- Customer No: ------------------- -------------- Software Vendor: IBM CORP ---------------
ACME CICS COMPANY
CELL BLOCK A
HURSLEY, WINCHESTER
Contact/Phone: MR WANNABE / +44 1962 815000
---------------------------- Processor ----------------------------
Category Type-Serial Model Begin-End Dates
---------- ---------- --------------- -----------------
Machine 2964-8E8C7 NE1 13Dec15 - 14Dec15
2964 CEC 2964-8E8C7 7A5 13Dec15 - 14Dec15
----------------- Maximum Concurrent Product Registrations -----------
----------------------- Product ----------------------2015 2016
Name Feature Version Number L| Dec Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
---------------- ---------------- -------- -------- -|---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Max MVS/ESA LPARs:| 1 - - - - - - - - - - - -
Percent Missing Hours:| 97 - - - - - - - - - - - -
|
# 13Dec15 |
|
z/OS Connect z/OS Connect 02.00.00 5655-CEE F| 19# - - - - - - - - - - - -
# 13Dec15 |
|
============================================================= Notes ================================================================
# - Data not collected for a full month.
N/A - Product registration counts are not available.
(01) - Not eligible for Measured Usage charges.
//IFAURP EXEC PGM=IFAURP,REGION=0M,PARM='PRODUCT'
//STEPLIB DD DSN=SYS1.SIFALIB,DISP=SHR
//IFAURP EXEC PGM=IFAURP,REGION=0M,PARM='PRODUCT'
//STEPLIB DD DSN=SYS1.SIFALIB,DISP=SHR
IFAURP usage reports
Maximum Concurrent Product Registrations – SMF 89 Type 2

43
Measured Usage and S/390 Usage Pricing Charges Page 2
IFAURP 4.1.2 Software Product Registration Report 14 DECEMBER 2015
------------------- Customer No: ------------------- -------------- Software Vendor: IBM CORP ---------------
ACME CICS COMPANY
CELL BLOCK A
HURSLEY, WINCHESTER
Contact/Phone: MR WANNABE / +44 1962 815000
---------------------------- Processor ----------------------------
Category Type-Serial Model Begin-End Dates
---------- ---------- --------------- -----------------
Machine 2964-8E8C7 NE1 13Dec15 - 14Dec15
2964 CEC 2964-8E8C7 7A5 13Dec15 - 14Dec15
----------------- Maximum Concurrent Product Registrations -----------------
----------------------- Product ----------------------2015 2016
Name Feature Version Number L| Dec Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
---------------- ---------------- -------- -------- -|---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Max MVS/ESA LPARs:| 1 - - - - - - - - - - - -
Percent Missing Hours:| 97 - - - - - - - - - - - -
|
# 13Dec15 |
|
z/OS Connect z/OS Connect 02.00.00 5655-CEE F| 1# - - - - - - - - - - - -
# 13Dec15 |
|
============================================================= Notes ================================================================
----------------------- Product ----------------------2015
Name Feature Version Number L| Dec
---------------- ---------------- -------- -------- -|----
Max MVS/ESA LPARs:| 1
Percent Missing Hours:| 97
|
# 13Dec15 |
|
z/OS Connect z/OS Connect 02.00.00 5655-CEE F| 19#
# 13Dec15 |
|
=============================================================
----------------------- Product ----------------------2015
Name Feature Version Number L| Dec
---------------- ---------------- -------- -------- -|----
Max MVS/ESA LPARs:| 1
Percent Missing Hours:| 97
|
# 13Dec15 |
|
z/OS Connect z/OS Connect 02.00.00 5655-CEE F| 19#
# 13Dec15 |
|
=============================================================
IFAURP usage reports
Maximum Concurrent Product Registrations – SMF 89 Type 2

45
IBM z/OS Connect Enterprise Edition (EE) V2.0 is the latest evolution of
z/OS Connect! z/OS Connect EE V2.0 is a priced offering, orderable via
Shopz as PID 5655-CEE.
Available now!Available now!
Announcement letter ENUS215-493
ibm.biz/zosconnect20_announce
z/OS Connect EE V2.0 includes
A dedicated Liberty profile for z/OS
• GA release includes Liberty V8.5.5.7
New Eclipse-based tooling for API composition with SWAGGER
• Delivered through IBM Explorer for z/OS V3.0 Aqua
The WOLA service provider for access to CICS and BATCH
• Including the WOLA Liberty feature
Utilities to generate service archives for use with CICS programs
• Creates JSON schemas as input for API composition
The REST client for access to “3rd
party” REST services
• e.g. JAX-RS applications hosted on WAS for z/OS
Product summary review

46
IBM IMS Enterprise Suite V3.2.1 is the latest release of components
that support open integration technologies to enable new application
development and extend access to IMS transactions and data.
IMS Enterprise Suite V3.2.1 includes
IMS Mobile Feature Pack for z/OS Connect Enterprise Edition
• The IMS mobile feature (service provider) for z/OS
Connect EE, enabling integration of IMS
Transactions with z/OS Connect EE
IMS Explorer for Development
• Support for generating service archives for use with
IMS transactions
IMS Enterprise Suite 3.2 Knowledge Center
IBM IMS Enterprise Suite V3.2.1
Delivers day-one support for z/OS Connect EE V2.0

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. (zCEE V2.0 APAR PI56615 / CICS TS V5.2 PI54207 / CICS TS V5.3 PI54208)
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. (Delivered ! IMS ES V3.2.1)
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.
Statements of general direction
ENUS215-493, December 1st, 2015
47

Notices and Disclaimers
48
Copyright © 2016 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission
from IBM.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM.
Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of
initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS
DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE
USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY. IBM
products and services are warranted according to the terms and conditions of the agreements under which they are provided.
Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice.
Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those
customers have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary.
References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries
in which IBM operates or does business.
Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials
and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant
or their specific situation.
It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and
interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such
laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law

Notices and Disclaimers Con’t.
49
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not
tested those products in connection with this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. IBM does not warrant the quality of any third-party products, or the
ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The provision of the information contained h erein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other
intellectual property right.
IBM, the IBM logo, ibm.com, Aspera®, Bluemix, Blueworks Live, CICS, Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document Management System™, FASP®,
FileNet®, Global Business Services ®, Global Technology Services ®, IBM ExperienceOne™, IBM SmartCloud®, IBM Social Business®, Information on Demand, ILOG,
Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®, PureData®,
PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®, SoDA, SPSS, Sterling Commerce®,
StoredIQ, Tealeaf®, Tivoli®, Trusteer®, Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business
Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM
trademarks is available on the Web at "Copyright and trademark information" at: www.ibm.com/legal/copytrade.shtml.

Thank You
Your Feedback is Important!
Access the InterConnect 2016 Conference Attendee
Portal to complete your session surveys from your
smartphone,
laptop or conference kiosk.

z Systems welcomes the next generation of
mainframers:
Generation z
The Workshop
A one day session exploring some the
exciting opportunities that come with
working on z Systems
The Mission:
To encourage the new generation of
technical experts into the exciting world
of mainframes
The Community
We have a wide network of virtual Gen z connections reinforced by meetups at key conferences
Join the community on Facebook: Ask a question on Reddit:
ibm.biz/ibmgenz /r/mainframe
Or find out more:
indi.singh@uk.ibm.com
GET INVOLVED!
52

CICS Development Services
Bringing CICS development expertise to your doorstep…
Need expert help?
Go to CICS Development Services, for worldwide services assistance
Workshops in:
Visit ibm.com/cics
then click ‘Services’
Custom /
Bespoke
Or
Email us CICSDTS@UK.IBM.COM 53

Resources
Redbooks – visit ibm.biz/cicsredbooks
Social Media – follow us on:
ibm.biz/cicsonfacebook
ibm.biz/cicsontwitter
ibm.biz/cicsonyoutube
0
DevCenter – visit
ibm.biz/cicsdevcenter
Knowledge Center – visit
ibm.biz/cicsknowledgecenter
54

IBM z/OS Connect EE
Further information

ibm.biz/zosconnect20_kc
Want to know more?
z/OS Connect EE Knowledge Center
56

IBM intends to provide Lab-based performance summaries
for z/OS Connect EE V2.0, with regular updates aligned with
the product continuous delivery lifecycle…
z/OS Connect EE V2.0 Performance
A sneak preview of our z13-based performance report…
57

Introducing the z/OS Connect for node.js project. Want to
contribute to it’s evolution? It’s happening in the open…
JavaScript programmers eat and breathe JSON & REST;
node.js is now the de-facto runtime framework used on the
server. Today, node.js is available on many platforms,
including Linux on z Systems.
github.com/zosconnect/zosconnect-node www.npmjs.com/package/zosconnect-node
A wrapper service for z/OS® Connect, enabling
node applications to discover and access IBM z
Systems resources that are service-enabled by
z/OS® Connect.
z/OS Connect support for node.js developers
58

ibm.biz/zAPI_Guide
IBM Redbooks guide
Mobile and API Economy
59

Demo Backup Slides
Create a Swagger-defined API using z/OS Connect

Activity: Service Development
Demo Backup Slides

Activity: Service Development
• zEE services are JSON-enabled z assets such as IMS and CICS transactions.
• zEE APIs enhance zEE services using natural REST mappings.
• At least one service should be created prior to starting API development.
• API development requires services to be exported to Service Archives (SAR).
• SAR file creation is supported by runtime-specific tooling:
– For IMS access through the IMS Mobile Feature Pack use:
– IMS Explorer for Development V3.2.1.
– For CICS access through WOLA, use the:
– BAQLS2JS and BAQJS2LS utilities.
62

63
z/OS Connect services
in IMS Explorer

64
Create a new
service in
IMS Explorer

65
Create a Service
Archive (SAR) file in
IMS Explorer

66
Choose where to
write the SAR file
Download generated
SAR file from z/OS
Connect server

67
SAR file is ready to be
checked into VCS/SCM

BAQLS2JS, BAQJS2LS: CICS through WOLA
• BAQLS2JS runs a version of the CICS utility DFHLS2JS.
• BAQJS2LS runs a version of the CICS utility DFHJS2LS.
• Use the SERVICE-ARCHIVE and SERVICE-NAME to generate a
Service Archive (SAR) for API development.
68

Activity: API Development
Demo Backup Slides

Activity: API Development
• Create a new z/OS Connect EE API Project.
– API Projects have the following structure:
• /api
– contains enhanced REST mappings of zEE services.
• /api-docs
– contains external description of API: swagger.json.
• /services
– contains zEE services imported from Service Archive (SAR) files
• package.xml
– describes the API to the zEE server. Edit this with the zEE API Editor.
• Use the zEE API Editor to define the API.
• Export an API Archive (AAR) file from the API Project.
• Deploy the AAR file to the zEE server.
70

71
Create a new zEE
API Project

72
Specify initial API
details (these can
be changed later)
Project will be created
and package.xml is
opened in the API Editor

73
New API
Project
Initial package.xml
opened in API Editor

74
Specify path with
path parameters and
query parameters
Query parameters
can be specified on a
per-method basis in
the mapping phase

75
Specify which zEE
service will handle
POST for this path

76
Select a service archive
from the eclipse
workspace or file
system
Already-imported
services can
simply be selected
Service archive will be
expanded and copied
into the API project
/services folder.

77
The service was
assigned.
Saving the API
causes the
swagger to update

78
For this example we’ll
assign the same service to
each method.
Having not yet defined
mappings, the swagger
contains the original
request and response
schemas from the service

79
Define mappings for the
phonebookService when
the method is POST

80
Start with the request
mapping. This is known
to the zEE server as
HTTP2JSON.
This mapping updates
the service’s request
JSON payload from the
HTTP request message.
Defining a request
mapping is optional.

81
The request JSON Schema
service that was assigned
to the POST method.
Request mapping is opened
in the Mapping Editor.

82
The service’s request body is passed
through as-is from left to right unless
mappings are defined.

83
Move Headers, Path
Parameters, and Query
Parameters to fields in
request payload of the
service.
Move mappings suppress target fields from the
external description of the method’s request
body as they are substituted by headers, path
parameters, or query parameters from the
HTTP Request (which are in the external
description of the method)

84
Assign a fixed value to
a field in the request
payload of the service.
This is typical for control
codes that the underlying z
asset needs, such as ADD,
UPD, DEL, DISP.
Specify the
fixed value
Specify whether
or not the value
acts as a default.

85
Defining a
response mapping
is optional.
Continue with the
response mapping. This
is known to the zEE
server as JSON2HTTP.
This mapping updates
the HTTP response
message from the
service’s response JSON
payload.

86
Response mapping is opened
in the Mapping Editor

87
The service’s response JSON payload
is passed through as-is from left to
right unless mappings are defined.

88
Remove mappings are used here
to prevent fields from the
service’s response payload from
appearing in the API.

89
To populate an HTTP
headers from a field in
the service’s response
payload, first add one.

90
The HTTP Response will now
contain a header named X-
SEGNO which contains the value
of the OUT_SEGNO field from the
service’s response payload.

91
Mappings for the POST method
have been completed. Mappings
for the remaining methods would
proceed in the same fashion.

92
When an API is ready to be
tested, export an API Package
from the API Project.

93
Choose where to write the
API Package (AAR) file.

94
Copy the AAR file to the
z/OS Unix Filesystem
AAR file is ready to
be checked into
VCS/SCM

95
z/OS Explorer includes
an export to z/OS Unix
File System Wizard
Rational Developer for
z includes more
comprehensive
support for working
with z/OS Files

96
Specify the remote
location to write the
AAR file.

97
The AAR file has been
transferred and is
ready to deploy.

Activity: API Deployment
Demo Backup Slides

Activity: API Deployment
• Use the API Deployment utility (apideploy) to deploy an API.
• The API archive file (AAR) must reside on a file system that the
apideploy utility can access.
• The user that runs the apideploy utility must have write permission to
the /resources directory.
• The apideploy utility is a supplied z/OS UNIX command, so the
deployer will need an OMVS shell to use the command.
99

Activity: API Validation
Demo Backup Slides

Activity: API Validation
• The zEE API Editor provides API composition only—therefore testing and
validation of APIs is required.
• To limit the complexity of validation, zEE services should be fully tested prior to
being used in a zEE API.
• Swagger SDK tools such as Swagger-UI, Swagger-Editor, Swagger-Codegen
are recommended for performing API validation.
102

103
Get a list of APIs
deployed to the
zEE server.
Follow the adminUrl to
obtain details on how to
invoke a particular API.

104
The apiUrl provides
the resolved URI for
invoking the API.
The resolved URI for
accessing the API’s
swagger definition.
Recall that
/contacts was the
API’s base path.

105
Swagger returned
from the zEE
server.

106
Swagger for an API can
be loaded directly from
the zEE server into the
Swagger Editor

107
The Swagger Editor
can be used to the
browse and validate
the design of the API.

108
loaded directly from the
zEE server into Swagger UI

109
Swagger UI can be used
to unit test methods
offered by the API.
Swagger Editor may also
be used for unit testing,
however it requires
Node.js whereas
Swagger UI does not.

110
The POST method did not
require a request body,
rather all of the input
data is carried on the URI.
This is the result of the
request mappings defined
in the zEE API Editor.
Note that response body
contains one field, per
the response mappings.
Note the x-segno
response header, per
the response mappings.

Make Your API Catalog Essential with z/OS Connect EE

More Related Content

What's hot (20)

Viewers also liked (10)

Similar to Make Your API Catalog Essential with z/OS Connect EE (20)

Recently uploaded (20)

Make Your API Catalog Essential with z/OS Connect EE

Editor's Notes