REST and the API Economy

—Kenishia CallawayNorth America Z Middleware Technical Specialistkenishia@us.ibm.com

MacKenna KelleherTechnical Solution SpecialistMacKenna.Kelleher@ibm.com

The way to adapt/adopt in the new API Economy, and even have an advantage over the new entrants is through leveraging Mainframe assets…

2

Key requirements for enabling digital transformation

3

AgilityMust be agile in responding to the changing marketplace needs and

competition

ReuseMust leverage existing assets

to support core business competency

Consumability, Control and Insight

Must make digital services easy to consume, while retaining tight

control over the delivery

System of Record (SOR) assets are built with a lot of due diligence and over a long period of time; People & processes are well integrated with these SOR assets

New digital presence applications need easy access to existing SOR data, i.e., with simpler easy-to-use interfaces

Replicating SOR data faces many disadvantages: Undue exposure risk, Stale data and High cost of propagating data

Solutions must be developed and deployed quickly, and are likely to be taken down just as quickly when replacing with newer solutions

An added requirement for enabling this multi-channel digital presence applications is flexible deployment of this solution as per the changing demands and available resources; i.e. cloud-based solutions

Digital delivery of services should be easy to find from catalogs and easy to subscribe

Access to the services should be controlled as per entitlement and accountability is required for monetization

Business insight via analytics into the access of these services is essential

Customization of delivered services based on real-time interaction with customers through digital applications

APIs are the new enterprise “product” …

4

Developers

Valuable, timesaving functions

Composable

Familiar interfaces (intuitive)

RESTful!

Well Documented

JSON!

Quickto

learnDiscoverable

And Developers (inside or outside the enterprise) are your new customers…

Exposing APIs and Enabling the Hybrid Cloud

5

Various ways to enable REST

These are typically not RESTful!

Completely different configuration and managementMultiple endpoints for developers to call/maintain access to

6

API-Enabling Z Systems: z/OS ConnectThe strategic REST API gateway for z Systems

7

CICS

IMS

DB2

MQ

…

z/OSConnect

EE

v z/OS Connect is a Gateway to your z/OS Subsystems

v “Fully REST” enable Major z/OS Subsystems• z/OS applications and data appear as any

other REST Provider

v Support of all REST verbs

v No Backend Application Changes

v No Coding Required (Tool Driven)

v Support of Open Standard Open API Doc (aka Swagger 2.0) for Integration with other products that support the standard

v Provide agile (dynamic) API creation, simple testing and easy deployment

v Enable “division of duties” between z/OS team and enterprise API team for fast time to deploy

v Developed on Continuous Delivery Model (quarterly target)

z/OS Connect EE 3rd Party Integrations

8

z/OS Connect EE is pluggable and extensible allowing 3rd Party Service Providers to expand the list of z/OS assets you can expose as APIs

Additional value from the ecosystem

API, Service Creation, & Deployment Process

9

Backend ProgramSource of copy book and target

of invocation

* Catalogue COMMAREA structure 03 CA-REQUEST-ID PIC X(6). 03 CA-RETURN-CODE PIC 9(2) DISPLAY. 03 CA-RESPONSE-MESSAGE PIC X(79).

* Fields used in Inquire Single 03 CA-INQUIRE-SINGLE.

05 CA-ITEM-REF-REQ PIC 9(4) DISPLAY.05 FILLER PIC 9(4) DISPLAY.05 FILLER PIC 9(3) DISPLAY.05 CA-SINGLE-ITEM.

07 CA-SNGL-ITEM-REF PIC 9(4) DISPLAY.07 CA-SNGL-DESCRIPTION PIC X(40). 07 CA-SNGL-DEPARTMENT PIC 9(3) DISPLAY.07 CA-SNGL-COST PIC X(6). 07 IN-SNGL-STOCK PIC 9(4) DISPLAY.07 ON-SNGL-ORDER PIC 9(3) DISPLAY.

Tooling and Utilities to extract JSON schema

from existing applications

API Definition

Services Definition

API and Services Creation

Dynamic API and Services Deployment

API Editor

zCEE Server Runtime

Service Projects & Service Creation

10

Import data structure

1

2 Redact fields, rename fields, and add descriptions to fields to make the service more consumable for an API developer

Specify connection reference and transaction id for service.

3

Import the data structure, define the service interface, & configure the service

z/OS Connect EE V3API Toolkit

IBM Explorer forz/OS Aqua V3.1

Define the URI path, http verbs and JSON mappings for the APIAPI Projects & API Creation

11

z/OS Connect EE V3API Toolkit

IBM Explorer forz/OS Aqua V3.1

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

1

3

2

Data Mapping

Group Name / DOC ID / Month XX, 2019 / © 2019 IBM Corporation 12

Developer friendly

APIs

Applications Unchanged

Use API Requestor to call External APIs from z/OS Assets

13

Make IBM Z the heart of your strategyTruly RESTful APIs to & from your mainframe

14

Get started with the open beta today: ibm.biz/zosconnectdc

The Other ConnectsA little clarity on what does what

DB2 ConnectProvides ODBC/JDBC access to DB2-housed data.

Clients/users would use SQL to formulate requests

No REST access

IMS ConnectTHE way to reach IMS Subsystem

OTMA client that provides TCP/IP connectivity to IMS applications/data.

Local access for WAS on z/OS

No REST access

AppConnectFormerly known as IIB or Message Broker

Any-any-connectivity between entities

Orchestration capability

REST access is possible

Typically requires specialist skills

15

Survey of the major options

16

Integration Solution Description When to Use

z/OS Connect Enterprise Edition IBM’s strategic REST gateway into

mainframe subsystems

Use 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 consideration for web service enabling CICS applications, particularly when you need to support multiple service requestor types or need bi-directional support

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

Most appropriate solution when service requestor is JEE component and when high QoS required (high availability, transactions, security)

IBM MQ IBM’s asynchronous messaging solution

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

Publish Swagger defined APIs from z/OS ConnectHow does z/OS Connect Integrate with API Connect?

17

z/OS Connect Automatically generates a Swagger document for each API that is created.

API Connect & z/OS Connect

18

CICSIMSMQDb2

API

APIAPI

Create APIs and microservices that consume IBM Z APIs

Manage and secure IBM Z APIs created by z/OS Connect

Comprehensive tooling that enables API developers to create RESTful APIs from z/OS-based assets

Delivers APIs as a discoverable resource using the OpenAPI specification (formerly Swagger)

IBM API Connect

The Scalable Multi-Cloud API Platform

A complete, modern and intuitive API lifecycle platform to create, securely expose and manage APIs across clouds to power digital applications

API Connect Components

20

Management System

Developer Portal

ServicesAnalytics Services

Gateway Services

IBM API Connect Functions and Flow

21

Consumer(Systems of Engagement)

Business Partner Apps

Mobile & Web Apps

Enterprise Internal Apps

Internet of Things

Secure

API Policy EnforcementEnterprise Security

Traffic control & mediationMonitoring/Analytics Collection

Manage

API DiscoveryAPI, Plan, Product, Policy Creation

Product Version & Lifecycle ManagementSelf-service App Developer Portal

API Monitoring & Analytics

API Gateway

APIC

man

aged

Mic

rose

rvic

es T

raff

ic

1 4

z System / Legacy Apps

Cloud Service

Application Server

ESB / Middleware

Data Store

Provider(Systems of Record)3

Create & Run

Develop & Compose MicroservicesConnect Microservices to data sources

Build, deploy, scale MicroservicesMonitor & debug Microservices

2 API Runtime

API Traffic

API Discovery with z/OS Connect

22

Provide the location of a

Swagger definition on

the z/OS Connect EE

server

Import APIs into API Connect by

referencing their Swagger definitions hosted on the z/OS Connect EE server.

You can now see your API within

API Connect

API Connect Perspectives: Management View

23

Create/Discover APIsManage access to APIsSecure APIs

IBM API Connect Developer Portal

24

View, Manage and Consume APIs

Demo

25

Parting Messages

26

z/OS Connect EE V3

Group Name / DOC ID / Month XX, 2019 / © 2019 IBM Corporation 27

APIs to and fromthe mainframe

Comprehensive subsystem support and unified tooling

Point-and-click API creation

v Create services and APIs using a common API Toolkit

v Call external APIs from your mainframe applications with the API requester support

v Simple integration into enterprise API management solutions

Key Messages on Hybrid Cloud and API Economy with Mainframe Assets

No industry can afford to

stand still, and a digital

presence is must, to

deliver new innovative

and improved services

with an extended

customer reach through

multiple channels and

partners

However, established

industries with well-

developed core

competencies, supported

by mainframe assets can

have an advantage over

new players

Also, API enablement is

essential for

sustainability of z System

based assets, supporting

ease of access to existing

SORs (and avoiding

moving applications and

data away from z)

28

1 2 3

Adapt to the disruptive changes in industry landscape (blurringtraditional Industry lines), enabled by APIsand in turn, by ease of delivery of new applications

Accelerate API Management with IBM API Connect and z/OS Connect EE for Enterprise Systems

Adopt z/OS Connect EE for ease of development and deployment of Systems APIs for accessing mainframe assets

Additional References

API for Dummies (Internet site – Register & Download) https://pages.apigee.com/global-ebook-apis-for-dummies-register.html

Product Pages>> z/OS Connecthttps://www.ibm.com/us-en/marketplace/connect-enterprise-edition>> API Connecthttps://www.ibm.com/cloud/api-connect

API Developer Communityhttps://developer.ibm.com/api/list

White Papers>> z/OS Connecthttps://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP102724>> API Connecthttps://www.ibm.com/downloads/cas/30YERA2R

Follow us on Twitter@ibmapimgt, @IBM

Youtube Channelyoutube.com/ibmapimanagement

29

30

/questions?thanks=trueThank you for your attention.

Appendix

Consumability of deployed Z services

32

Key z Services are hard to discover and consumeDifficult for internal partners and developers to discover & access key services

• Key z services should be easy to look up by internal developers as well as external partners and end-consumer app developers via a browsable catalog of APIs• Consumable service description needs to include description of business function,

detailed description of various information field, and example on how to invoke a service• Deployed z based web services (CICS, IMS and WAS) quite often are not published into a

service registry

• Self-registration of consuming applications, and entitlement set up makes APIs more consumable • Additionally, REST/JSON based services are easier to consume by mobile apps

z/OS Connect EE

REST stands for Representational State Transfer.

An architectural style for accessing and updating data.

Typically using HTTP… but not all HTTP interfaces are “RESTful”.

Simple and intuitive for the end consumer (the developer).

HTTP

REST is an Architectural Style

z/OS Connect EESome red flags…(How to know if you are doing it wrong)

1. Unique URIs for different operations on the same object

2. Different representations of the same objects

3. Operational data in the request body

http://www.acme.com/customers/GetCustomerDetails/12345http://www.acme.com/customers/UpdateCustomerAddress/12345?address=

POST http://www.acme.com/customersBODY { “firstName”: “Joe”,

“lastName” : “Bloggs”,“addr” : “10 Old Street”,“phoneNo” : “01234 0123456” }

RESPONSE HTTP 201 CREATEDBODY { “id” : “12345”,

“name” : “Joe Bloggs”,“address”: “10 New Street”“tel” : “01234 0123456”}

POST http://www.acme.com/customers/12345BODY { “updateField”: “address”,

“newValue” : “10 New Street”}

RESPONSE HTTP 200 OKBODY { “id” : “12345”,

“name” : “Joe Bloggs”,“address”: “10 New Street”“tel” : “01234 123456”

}

z/OS Connect EEWhy is REST popular?

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

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.

Stateless REST 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.

/swagger/open_apiThe industry standard framework for describing RESTful APIs.

z/OS Connect EEWhy use Swagger?It is more than just an API framework

Write Swagger

Swagger Editor allows API developers to design their swagger documents.

Read Swagger

Swagger UI allows API consumers to easily browse and try APIs based on Swagger Doc.

Consume Swagger

Swagger Codegen create stub code to consume APIs from various languages

There are a number of tools available to aid consumption:

z/OS Connect EEHow do we expose z/OS data and services as RESTful APIs?

z/OS Connect EE

High level security options available in z/OS Connect EE

http://ibm.biz/zosconnect-security

z/OS Connect EE

API provider security flow

1. Client credentials2. Identity passed on connection3. Authenticate the client4. Map authenticated identity to a user ID

5. Authorize the authenticated user ID6. Audit the request7. Secure connection to System of Record8. Use asserted identity in System of Record

http://ibm.biz/zosconnect-security

z/OS Connect EE

API requester security flow

1. z/OS program can provide user ID & password2. Send request on secure connection3. Authenticate the credentials4. Authorize the authenticated user ID

5. Audit the request6. Obtain token from authorization server7. Secure connection to API provider with security token 8. RESTful API runs in API provider

http://ibm.biz/zosconnect-security

Strategic REST API Solutions

42

Integration Solutions Description Recommendation

z/OS Connect EE v3 Strategic solution for enabling REST APIs based on z/OS applications.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 APIsManage 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.

What’s wrong with this picture?

43

These Microservices are exposed to the open web!

www

Firewall

Orders Microservice

Runtime (Node.js, WAS,

etc.)

Product Detail Microservice

Runtime (Node.js, WAS, etc.)

Integration Tier

Systems of Record

Product data

Orders data

Traditional Business

You need an API Gateway

44

www

Firewall

Integration Tier

Systems of Record

Product data

Orders data

Traditional Business

API

API Gateway(rate limiting, security)

API

Orders Microservice

Runtime (Node.js, WAS,

etc.)

Product Detail Microservice

Runtime (Node.js, WAS, etc.)

You AT LEAST need:• Rate limiting• Security

…an API Gateway

NOTE: Firewall could be internet-facing or between internal networks