Chapter 21: Key Takeaways
Core Concept
API-first COBOL means exposing existing mainframe business logic as RESTful APIs without changing the underlying COBOL programs. z/OS Connect EE translates between REST/JSON and COBOL/COMMAREA; an API mediation layer handles routing, security, rate limiting, and developer experience.
10 Things to Remember
1. Your COBOL Programs Don't Change
z/OS Connect handles the impedance mismatch between the REST/JSON world and the COBOL/COMMAREA world. Your COBOL program receives a COMMAREA and returns a COMMAREA, exactly as it would from a 3270 screen. The API layer is additive, not invasive.
2. z/OS Connect Has Three Layers
API Definition (OpenAPI spec) defines what consumers see. Service Archive (.sar) contains the JSON-to-COBOL data mapping. Service Provider (CICS, MQ, DB2, IMS) connects to the backend. Understand each layer's responsibility.
3. COMP-3 Precision Kills
COBOL packed decimal fields (COMP-3) can hold more precision than JSON number (IEEE 754 double). For financial amounts, map COMP-3 to JSON string with a documented decimal format. Never map large monetary values to JSON number.
4. COMMAREA Has a 32,763-Byte Limit
If your API response exceeds this, use CICS channels and containers instead. z/OS Connect supports both, but you must configure the service archive accordingly.
5. The API Gateway Is Not z/OS Connect
z/OS Connect translates protocols. The API gateway (Zowe API ML or API Connect) manages cross-cutting concerns: routing, load balancing, authentication, rate limiting, monitoring, and developer portal. They are complementary, not interchangeable.
6. Rate Limiting Protects Mainframe Capacity
Without rate limiting, a single API consumer can starve your CICS region. Configure consumer-specific rate limits. Consider dynamic rate limiting based on real-time mainframe utilization.
7. Map COBOL Response Codes to HTTP Status Codes
Don't leak internal COBOL response codes or CICS abend codes through the API. Map them to proper HTTP status codes (200, 400, 404, 500, 503) with generic error messages and correlation IDs for tracing.
8. OAuth2 + RACF = Mainframe API Security
OAuth 2.0 provides authentication and authorization at the API layer. RACF provides authorization at the mainframe layer. z/OS Connect's SAFCredentialMapper bridges the two by mapping OAuth identities to RACF user IDs.
9. API Versioning Is Not Optional
Use URL path versioning (/api/v1/, /api/v2/). Additive changes (new optional fields) don't require a new version. Breaking changes (removed fields, type changes) do. Support at most two active versions. Deprecated versions get 6-12 months before retirement.
10. Treat APIs as Products
APIs need product owners, roadmaps, consumer feedback, documentation, and SLAs. "We have APIs" is not enough. "We have a managed API platform with governed lifecycle and measured outcomes" is the target.
Common Mistakes to Avoid
- Exposing raw COBOL field names in JSON — Translate
ACCT-CUST-LST-NMtoaccountCustomerLastName - Using HTTP POST for everything — Use GET for reads, POST for creates, PUT for full updates, PATCH for partial updates, DELETE for deletes
- Returning HTTP 200 for errors — Use proper HTTP status codes; consumers expect them
- Skipping the API gateway — Exposing z/OS Connect directly to consumers loses rate limiting, analytics, and centralized security
- Ignoring character encoding — EBCDIC-to-UTF-8 conversion requires the correct code page configuration
- No audit logging — Every API call should be logged for security, compliance, and operational analysis
- No deprecation strategy — APIs accumulate. Without versioning and deprecation governance, you end up maintaining every API you ever built
Quick Reference
| Component | Purpose | Key Config |
|---|---|---|
| z/OS Connect EE | REST/JSON ↔ COBOL/COMMAREA translation | server.xml, .sar files |
| Service Archive (.sar) | Data mapping + backend connection | API toolkit or zconbt |
| CICS Service Provider | Invokes CICS programs via IPIC | zosconnect_cicsIpicConnection |
| Zowe API ML Gateway | Routing, LB, security, monitoring | Gateway config YAML |
| Zowe Discovery Service | Service registry for z/OS Connect instances | Eureka-based registration |
| API Connect | Enterprise API management + developer portal | API Manager console |
| SAFCredentialMapper | OAuth identity → RACF user ID | z/OS Connect security config |
Connecting to Other Chapters
- Chapter 13 — CICS regions host the backend programs your APIs call. TOR/AOR routing still applies.
- Chapter 14 — First-generation web services in CICS. z/OS Connect is the second generation, providing cleaner separation.
- Chapter 19 — MQ enables asynchronous API patterns. Fund transfer APIs use request-reply queues behind the scenes.
- Chapter 20 — Event-driven patterns complement APIs. APIs are synchronous request/response; events are asynchronous notifications.
- Chapter 22 — The reverse direction: COBOL programs consuming cloud APIs through z/OS Connect's API requester pattern.