API’s, Db2’s Native REST Support and z/OS ConnectMark TurnerRoyal Bank of Scotland

07/11/2017Session IC

Agenda• What is REST• Db2 Native REST support • Installing Db2 REST• Creating, Running & Dropping Services• zOS Connect Introduction

What is REST?• REpresentational State Transfer• An architectural style often used in the development of

web services• More lightweight than SOAP (Simple Object Access

Protocol)• Stateless

– A single unit of recovery– Essentially the architecture of the internet

• Responses returned as JSON

Why use REST?

• Quick time to market– Reuse existing assets and services

• Relatively easy to program• Opens up new markets• The API ‘Economy’

The API Economy

Bank APIs

MortgagesLoans

Acct Enquiryetc

Car Dealer

Finance Comparison

Site

Estate Agent

One Stop Banking App

What is the Db2 REST API• Implements HTTP protocol as part of DDF

• Executes a single SQL statement– SELECT, INSERT, UPDATE, or DELETE– CALL proc

• Executes as static SQL• Does not require Db2 Connect driver or license

Db2 for z/OSDDF

DRDA

HTTP(s)

App Server / Client

ODBC / JDBC / CLI

REST Client

HTTP(s)

REST Overview

REST Client

REST Listener(Db2)

POST /account/deposit

{“account” : “12345678”,“amount”: “100.00”

}

Response{“deposit” : “successful”

}

{“account” : “12345678”,“balance” : “1100.00”

}

GET /account/balance{“account” : “12345678”,

}

Response

Update Account

SP

AccountEnquiry

SP

Db2 REST Limitations

• IDAA access is not supported– Restriction will be lifted in the future

• Remote DRDA requests are not supported– Restriction may be addressed in the future

• DB2 System profile monitoring is not supported– Restriction will be lifted in the future

Installing Db2 REST

Db2 Support for REST• Information APAR

– II14827 – Lists limitations and APARs that lift those restrictions

• Db2 V11– PI66828 – Base REST delivery– PI70477 – Removes message size limitations– PI80087 – Client Certificate and Trusted Context support– PI81224 – Fixes zero length input parm abend– PI86867 – ‘Multiple improvements’

• Db2 V12– PI70652 – Base delivery– PI80088 – Client Certificate and Trusted Context support– PI81225 – Fixes zero length input parm abend– PI86868 – ‘Multiple improvements’

Enabling Db2 Support

• Create new DSNR profile– RDEF DSNR (ssid.REST) UACC(NONE)– PERMIT ssid.REST CLASS(DSNR) ID(DB2USER) ACCESS(READ)

• Create new ‘catalog’ table – SYSIBM.DSNSERVICE– ‘DB2.SDSNSAMP(DSNTIJRS)’

• Consider enabling Db2 TLS/SSL support– Uses SECPORT

Verifying Installation• Using Web Browser, or a REST client:

http://db2host:db2port/services

Note: Internet Explorer treats JSON as a file to be downloaded.

{ "DB2Services": [ {

"ServiceName": "DB2ServiceDiscover","ServiceCollectionID": null,"ServiceDescription": "DB2 service to list all available services.", "ServiceProvider": "db2service-1.0","ServiceURL": "http://dsb0dist.plexs1.server.rbsgrp.net:4501/services/DB2ServiceDiscover"

}, {

"ServiceName": "DB2ServiceManager","ServiceCollectionID": null, "ServiceDescription": "DB2 service to create, drop, or alter a user defined service.", "ServiceProvider": "db2service-1.0", "ServiceURL": "http://dsb0dist.plexs1.server.rbsgrp.net:4501/services/DB2ServiceManager"

}]}

Creating a Db2 REST Service• A Db2 REST Service =

– Stored Procedure

– Single SQL statement• Data Studio does NOT support creating Db2 REST

services• Use a REST client to invoke Db2 System service

‘DB2ServiceManager’– Browser REST plugin– Desktop client– Roll your own (see article by Triton’s ‘DB2 Dinosaur’, James Gill,

for a php example)

Security Requirements• READ access to DSNR ssid.REST• BINDADD• PACKADM on the service collection

Db2 REST Test Case

• Uses Db2 Sample database– DEPT and EMPLOYEE tables

• Create Stored Procedure to list all Employees for a specified department

• Expose Stored Procedure as a REST service

Test Case Stored Procedure

Creating a Db2 REST Service• URI

POST http://db2host:db2port/services/DB2ServiceManager

• HeaderAccept: application/jsonContent-Type: application/json

• JSON Body{

"requestType": "createService","sqlStmt": "<sqlStatement>","collectionID": "<serviceCollectionID>","serviceName": "<serviceName>","description": "<serviceDescription>","<bindOption>": "<bindOption>"

}

Creating a Db2 REST Service• Request

Creating a Db2 REST Service• Response

What gets Created?• DB2 Package

LOCATION COLLID NAME CONTOKEN-------- ------ ------------ --------

Sample GetEmployees HTTPREST

• SQL in Package

-- SQL statements in PACKAGE : Sample.GetEmployees.()call GETEMPLOYEES (:dept, :errmsg)

• SYSIBM.DSNSERVICE

NAME COLLID CONTOKEN ENABLED---------------- ---------- -------- -------GetEmployees Sample HTTPREST Y

List REST Services

{"DB2Services": [

{"ServiceName": "DB2ServiceDiscover","ServiceCollectionID": null,"ServiceDescription": "DB2 service to list all available services.", "ServiceProvider": "db2service-1.0","ServiceURL": "http://dsb0dist.plexs1.server.rbsgrp.net:4501/services/DB2ServiceDiscover"

}, {"ServiceName": "DB2ServiceManager","ServiceCollectionID": null, "ServiceDescription": "DB2 service to create, drop, or alter a user defined service.", "ServiceProvider": "db2service-1.0", "ServiceURL": "http://dsb0dist.plexs1.server.rbsgrp.net:4501/services/DB2ServiceManager"

},

{"ServiceName": "GetEmployees", "ServiceCollectionID": "Sample","ServiceDescription": "List Employee names that work for a given department","ServiceProvider": "db2service-1.0","ServiceURL": http://dsb0dist.plexs1.server.rbsgrp.net:4501/services/Sample/GetEmployees

}]

}

GET http://db2server:db2port/services/

List Service RequirementsGET http://db2server:db2port/services/Sample/GetEmployee

• Request Schema

List Service Requirements• Response Schema – Parameters Description

• Response Schema – Results Set Description

List Service Requirements

Run the ServicePOST http://db2server:db2port/services/Sample/GetEmployee

Run the Service

• Run Service Response

Drop a Service• URI

POST http://db2host:db2port/services/DB2ServiceManager

• HeaderAccept: application/jsonContent-Type: application/json

• JSON Body{

"requestType": “dropService","collectionID": "<serviceCollectionID>","serviceName": "<serviceName>"}

Drop a Service

Why use an API Gateway?• Db2 only supports POST and GET

– PUT and DELETE not supported

• Provide a single service/service discovery gateway for z/OS– Other services may exist – e.g. CICS, IMS, Batch etc

• Consistent auditing, logging and authorisation

• Expose Services as one or more APIs

Services vs APIs• Services

– POST /accounts/create + JSON with account create info– POST /accounts/balance + JSON with account number– POST /accounts/update + JSON account number and

credit/debit amount

REST interface is limited and may fall short of what developers require/expect

• APIs– POST /accounts?name=John + JSON with John’s info– GET /accounts?number=1234– PUT /accounts?number=1234 + JSON with credit/debit amount

HTTP verb conveys method against the resource

URI conveys resource being acted upon

JSON body contains specific data for the action & resource

More aligned with developers requirements/expectations

z/OS Connect Architecture

RESTClient

Liberty Profile z/OS Runtime

z/OS Connect EE

Interceptors

CICS

DB2

IMS

MQ

Discovery Audit Logging Authorisation

z/OS ConnectAPI Editor

Ser

vice

Pro

vide

rs

DataTrans-form

2 1 4

3

5

6

1 zOS Connect is a servlet that runs in Liberty Profile 3

Interceptors are callout points to invoke common services –authorisation,logging etc

5Service providers provide the connectivity to the backend systems

2 zOS Connect accepts REST URIs and JSON data 4

Data transformation translates client requests to format expected by backend

6 Backend systems supported by zOS Connect

REST Client

Creating a z/OS Connect Service

CICS

DB2

IMS

MQ

API Mapping/Transform

Interceptors

ServiceProviders

POST

GET

PUT

DELETE

z/OS Connect EELiberty Profile for z/OS

1. Create Service Archive

z/OS Connect API Editor

2. Create API

3. Deploy API

4. Discover API

5. Invoke API

Swagger 2.0 Description

Thank You

Session feedback

• Please submit your feedback online at:

http://conferences.gse.org.uk/2017/feedback/IC

• Paper feedback forms also available from the Chair person

• This session is IC