Best practices for API development, devops, and IMS security with z/OS Connect.

1. 2018 IBM Systems
Technical University
May 14-18, 2018
London, UK
z101666: Best Practices for
Delivering Hybrid Cloud Capability
with APIs
—
Teodoro Cipresso
z/OS Connect EE API toolkit Lead
Haley Fung
IBM IMS Offering Manager

2. 2IBM IMS / May 9, 2018 / © 2018 IBM Corporation
Introductions
Haley Fung
IMS Offering Manager
Ted Cipresso
z/OS Connect EE API
toolkit lead

3. Please note
IBM’s statements regarding its plans, directions, and intent are subject to change
or withdrawal without notice and 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 remains at our sole discretion.
Performance is based on measurements and projections using standard IBM benchmarks in
a controlled environment. The actual throughput or performance that any user will
experience will vary depending upon many factors, including considerations such as the
amount of multiprogramming in the user’s job stream, the I/O configuration, the storage
configuration, and the workload processed. Therefore, no assurance can be given that an
individual user will achieve results similar to those stated here.
Replace the footer with text from the PPT-Updater. Instructions are included in that file. 3

4. Please
complete
the session
survey!
4Replace the footer with text from the PPT-Updater. Instructions are included in that file.

5. © 2018 IBM Corporation
Best Practices for API and Service Development
IBM z/OS Connect Enterprise Edition
Teodoro Cipresso
z/OS Connect EE API toolkit Lead
cipresso@us.ibm.com

6. What process should I
adopt for developing
APIs and services?
6
© 2018 IBM Corporation

7. Service Development with API toolkit
7
Test service
Check service
project into
SCM/VCS
Design
interfaces &
specify
properties
“Right click”
Deploy service
project to dev
server
Service
Developer
Service
exists?
Create new
service project
Check out
service project
from
SCM/VCS
Workflow for a z/OS Connect service developer
DevOps with
z/OS Connect
SARs
Service
projects
Yes
No

8. 8
Test API
operation
Check API
project into
SCM/VCS
Design and
implement API
operation
“Right click”
Deploy API
project to Dev
server
API Developer
API
exists
?
Create new API
project
Check out API
project from
SCM/VCS
Yes
No
Download or
Check out
SARs to import
API Development with API toolkit
Workflow for a z/OS Connect EE API developer
DevOps with
z/OS Connect
AARs
API
projects

9. z/OS Connect EE
9
Automate the development and deployment of services, APIs, and API requesters for continuous integration and delivery.
• The build toolkit supports the generation of service archives and API archives from projects created in the z/OS Connect EE API
toolkit
• The build toolkit also supports the use of properties files to generate API requester archives
• Run the build toolkit from a build script to generate these archive files
• Deploy them to z/OS Connect servers by copying them to their dropins folders or by using the REST Admin API
ibm.biz/zosconnect-devops
DevOps using z/OS Connect EE
© 2018 IBM Corporation

10. z/OS Connect EE
10ibm.biz/zosconnect-devops
DevOps Pipeline using z/OS Connect EE
© 2018 IBM Corporation

11. z/OS Connect EE
11ibm.biz/zosconnect-devops
DevOps Pipeline using z/OS Connect EE
Example pipeline technologies
© 2018 IBM Corporation

12. What options do I have
for versioning APIs?
12

13. Sampling API Versioning Articles
13
Same or similar strategies, but no consensus on which one to use
RESTful API Versioning Insights
https://blog.restcase.com/restful-api-versioning-insights
Your API versioning is wrong, […] I decided to do it 3 different wrong
ways
https://www.troyhunt.com/your-api-versioning-is-wrong-which-is
Introduction to API Versioning Best Practices
https://nordicapis.com/introduction-to-api-versioning-best-practices
RESTful API Versioning Best Practices: Why v1 is #1
https://www.sparkpost.com/blog/api-versioning-best-practices
Versioning a REST API
http://www.baeldung.com/rest-versioning
REST API Versioning - Is There a Right Answer?
https://dzone.com/articles/rest-api-versioning-is-there-a-right-answer
Interesting point of view that it might
be possible to be V1 forever…

14. Options for Versioning APIs
14
Discuss some versioning options from the literature
Augment JSON API Accept Header
Accept: application/vnd.bankapi.v20+json
Use a query parameter
https://host:port/bankapi/account?version=2.0
Specify the version in the URL
https://host:port/bankapi/v20/account
Doesn’t break existing clients, easy to use,
but has a URI footprint.
Honorable mention: Domain versioning…(v2.host:port)
Use a custom request header
X-API-Version: 2.0
Preserves the URI across versions of the
API, but has low affordance (not obvious).
JSON:API is a spec for formatting JSON
responses. This takes liberty of the spec.
Not clear what is being versioned here.
The overall API or the account resource?

15. How can I verify that
my API design is
RESTful?
15

16. API Design Checklist
16
Quick and simple API design validation points
URIs should resolve to a resource, sub resource or collection
POST /api/customers, /api/customers/{cid}/orders
POST /api/createCustomer, /api/createOrder?cid
Provide ways to limit the amount of data returned
GET /api/customers?limit, /api/customers/{cid}/orders?limit
GET /api/customers, /api/customers/orders

17. API Design Checklist
17
Quick and simple API design validation points
Allow for filtering and pagination of data
GET /api/customers/{cid}/orders?offset&limit
GET /api/customers/orders
DELETE /api/customers/{cid}, /api/customers/{cid}/orders/{oid}
DELETE /api/customers, /api/customers/orders
Try to avoid DELETE with collections

18. API Design Checklist
18
Quick and simple API design validation points
If possible, wait to version your API until after V1
https://../bankapi/../, https://../bankapi/v2/../
https://../bankapi/v1/../
Do not version resources, only version the API
https://../api/v2/customers/{cid}/orders
https://../api/v2/customers/{cid}/v1.1/orders

19. © 2018 IBM Corporation
Configuring z/OS Connect for IMS
IBM z/OS Connect Enterprise Edition
Haley Fung
IMS Offering Manager
hfung@us.ibm.com

20. How can I configure
z/OS Connect and IMS
to meet my security
audit requirements?
20

21. z/OS Connect Security
21
Encryption
• TLS/SSL
Authentication
• Basic
• client certificates
• 3rd party
authentication
Authorization
• API and Services
Role and group
access
ID propagation
• Propagate ID to
the backend
subsystem. For
example,
• IMS Connect
authentication
• IMS transaction
authorization

22. Authentication
Third-Party AuthenticationBasic Authentication Client Certificate
Server prompts for ID/PW
Client supplies ID/PW
Server checks registry:
 Basic (server.xml)
 LDAP
 SAF
REST
Client
z/OS Connect EE
ID/PW Okay!
REST
Client
z/OS Connect EE
Okay!
TLS
Client
Cert
Could be
a trusted
server
Server prompts for cert.
Client supplies certificate
Server validates cert and
maps to an identity
Trusted
Server
z/OS Connect EE
Token (JWT, LTPA, other)
REST
Client
3rd Party
ID/PW
Auth
Okay
= 'FRED'
Identity Mapping
Client authenticates to 3rd party sever
Client receives a trusted 3rd party token
Token flows to Liberty z/OS across
trusted connection and is mapped to an
identity

23. End-to-End Security and ID
propagation Considerations
23
Internet
Banking
Customer
Internal User
RACF User ID /
password
Internet
Banking
Secure
Gateway
Customer
IMS
Connect
IMS
z/OS
Connect
z/OS
Internet
User ID /
password
z/OS Connect
Authentication ?
IMS Connect
Authentication ?
IMS
Authorization ?

24. Scenario #1 – Shared ID with IMS Connect RACF=Y
Connection Profile
UserID, Pwd
SID
SPWD
zCEE
HTTPS
Already
authenticated
CID
IMS Connect
AT-TLS
TCP/IP
RACF = Y
SID
SPWD
RACF
Authentication SID SPWD
IMS
Authorization
SID
SID
SID SPWD = A Shared User ID/Password specified in the connection profile
CID CPWD = User ID/Password of the originating client
RID = RACF Mapped ID (No Password)
Client
Secure
Gateway
Authenticate

25. Scenario #2 – Client ID and IMS Connect RACF = N
CID CPWD = User ID, Password of the originating client
IMS
CID
Authorization CID
RACF
CID
(No
CPWD)
Authentication
CID CPWD
IMS Connect
AT-TLS
TCP/IP
RACF = N
CID
(No Authentication)
Connection Profile
UserID, Pwd
(No AuthData)
Best for POC
zCEE
HTTPS
CID
CPWDClient

26. Scenario #3 – Client ID and IMS Connect RACF = Y
26
IMS
RID
Authorization RID
RACF
Authentication
CID CPWD
ID Mapping CID -> RACF ID
RID
CID CPWD = User ID, Password of the originating client
RID = RACF Mapped ID
Connection Profile
UserID, Pwd
(No Authdata)
IMS Connect
AT-TLS
TCP/IP
RACF = Y
RID
Required: Modify HWSJAVA0
to check if incoming request is
from zCEE and set
TrustedUser flag to True to
bypass authentication
Authentication (Bypass
Authentication for
zCEE request)
zCEE
HTTPS
CID
CPWDClient

27. Scenario #4 – Future Requirement – Client UToken
27
IMS
UTOKEN
Authorization UTOKEN
UTOKEN
(Sync-to-OS-Thread)
CID ->
UTOKEN
RACF
Authentication
CID CPWD
CID
CID CPWD = User ID, Password of the originating client
RID = RACF Mapped ID (No Password)
UTOKEN = Identity of originating client
Connection Profile
UserID, Pwd
(No Auth data)
IMS Connect
AT-TLS
TCP/IP
RACF = Y
UTOKEN
Optional: Modify the
HWSJAVA0 to set Trusted
User Flag to True to bypass
RACF check. Otherwise, IMS
Connect will authenticate
UTOKEN
Authentication (Optionally
bypass if Trusted
User flag = True)
zCEE
HTTPS
CID
CPWDClient

28. Scenario #5 – Future Requirement – Client User ID/Pwd + RACF=Y
28
Client
UserID, Pwd
CID
CPWD
IMS
CID
Authorization CID
CID CPWD = User ID, Password of the originating client
RID = RACF Mapped ID (No Password)
Connection Profile
UserID, Pwd
(No Authdata)
IMS Connect
AT-TLS
TCP/IP
RACF = Y
CID
CPWD
RACF
Authentication CID
CPWD
Authentication
CID CPWD
ID Mapping CID -> RID
RID
RACF
zCEE
HTTPS
CID
CPWDClient

29. How can I configure
z/OS Connect and IMS
to handle the API
workload?
29

30. High Availability
30

31. High Availability with IMS
31
SysplexDistributor
IMS Connect
IMS Connect
IMS
IMS

32. Thank you
32
Teodoro Cipresso
z/OS Connect EE API toolkit Lead
cipresso@us.ibm.com
Haley Fung
IBM IMS Offering Manager
hfung@us.ibm.com

33. 33