Chapter 21 Exercises: API-First COBOL

Section 21.1 — The API-First Mindset

Exercise 1: Integration Pattern Analysis

Your organization currently uses the following integration patterns for its mainframe systems: - Nightly FTP batch extract of customer records to a CRM system (2.1 million records) - Hourly screen-scraping of 3270 transaction status screens by a monitoring tool - Real-time MQ messages for inter-system payment processing - Weekly tape export of regulatory reporting data

For each integration, determine whether it should be converted to an API, remain as-is, or use a hybrid approach. Justify each decision based on latency requirements, data volume, consumer needs, and cost-benefit analysis.

Exercise 2: API-First Business Case

Write a one-page business case for converting SecureFirst's claims processing system from batch file integration to API-first. The current system exports claims data via nightly FTP to three downstream systems: fraud detection, actuarial analysis, and regulatory reporting. Include estimated cost, timeline, risks, and benefits. Use the metrics from Section 21.1 as reference points.

Exercise 3: Identifying API Candidates

Given the following CICS transaction inventory, rank the transactions by API exposure priority (1 = highest). Consider consumer demand, data sensitivity, transaction complexity, and business value.

Exercise 4: File Transfer Cost Analysis

Calculate the total annual cost of maintaining a nightly file transfer integration that moves 500,000 records (average 800 bytes each) from the mainframe to a cloud database. Include: - Mainframe CPU for extract job (estimate 15 minutes of batch processing at $200/CPU-hour) - Network transfer costs - Cloud storage for the replicated data - Synchronization monitoring and incident response (estimate 2 hours/month operations staff time) - Data staleness cost (estimate 3 customer complaints per week due to stale data, each costing $50 in service recovery)

Compare this to an API-based approach where the cloud system queries the mainframe on demand (estimated 50,000 API calls/day at 200ms average).

Exercise 5: Anti-Pattern Identification

Identify the API anti-patterns in the following scenario and explain how to fix each one:

A development team at CNB has exposed a COBOL program as an API. The API: - Returns the raw COBOL COMMAREA as a JSON blob with field names like ACCT-CUST-LST-NM - Uses HTTP POST for all operations (inquiry, update, delete) - Returns HTTP 200 for all responses, including errors, with a status field in the body - Requires the consumer to pass the CICS transaction ID in a header - Has no versioning strategy - Returns COBOL abend codes in error messages

Section 21.2 — z/OS Connect EE

Exercise 6: Architecture Diagram

Draw a complete architecture diagram for a z/OS Connect EE deployment that serves three consumer types: a mobile application, a partner API, and an internal batch job. Show: - Network zones (DMZ, internal, mainframe) - z/OS Connect instances (how many? where?) - Backend connections (CICS, DB2, MQ) - Load balancing - Authentication flow for each consumer type

Exercise 7: Service Provider Selection

For each of the following API requirements, identify the correct z/OS Connect service provider and explain why:

a) Real-time policy inquiry that reads from a VSAM file via a CICS program b) Ad-hoc SQL query against a DB2 claims database c) Asynchronous message submission to an MQ queue for batch processing d) IMS transaction for legacy account maintenance e) A composite API that reads from DB2 and then updates via CICS

Exercise 8: COMMAREA Design for API

Design a COBOL COMMAREA layout for a customer address update API. The API must: - Accept a customer ID (10 digits) - Accept a new address (street, city, state, ZIP, country) - Support partial updates (only changed fields are provided) - Return the updated address and a timestamp - Handle error conditions (customer not found, invalid state code, address validation failure)

Write the COBOL copybook and explain how each field maps to the JSON request/response.

Exercise 9: z/OS Connect Configuration

Write a server.xml configuration for z/OS Connect EE that: - Enables CICS and MQ service providers - Configures two CICS IPIC connections (primary and backup) with weighted routing (80/20) - Enables SSL/TLS with a keystore - Configures an HTTPS endpoint on port 9443 - Enables the health check endpoint

Exercise 10: Channel/Container vs. COMMAREA

A COBOL program needs to return a variable-length list of up to 5,000 transaction records, each 200 bytes. Calculate the total data size and determine whether to use COMMAREA or channels/containers. Document the trade-offs and write the z/OS Connect service archive configuration for the approach you choose.

Exercise 11: COMP-3 Precision Testing

Write a test case that demonstrates the COMP-3 precision loss problem described in Section 21.2. Given a COBOL field PIC S9(15)V99 COMP-3, show: - A value that would lose precision if mapped to JSON number type - The correct JSON string representation - How the OpenAPI schema should document this field

Section 21.3 — OpenAPI for COBOL

Exercise 12: Copybook-to-OpenAPI Mapping

Convert the following COBOL copybook to a complete OpenAPI 3.0 components/schemas section:

       01  POLICY-INQUIRY-RESP.
           05  PIR-RESP-CODE        PIC 9(02).
           05  PIR-POLICY-DATA.
               10  PIR-POLICY-NUM   PIC X(12).
               10  PIR-HOLDER-NAME  PIC X(40).
               10  PIR-EFF-DATE     PIC 9(08).
               10  PIR-EXP-DATE     PIC 9(08).
               10  PIR-STATUS       PIC X(01).
               10  PIR-PREMIUM      PIC S9(07)V99 COMP-3.
               10  PIR-COVERAGE-AMT PIC S9(09)V99 COMP-3.
               10  PIR-RIDERS OCCURS 5 TIMES.
                   15  PIR-RIDER-CODE PIC X(04).
                   15  PIR-RIDER-DESC PIC X(30).
                   15  PIR-RIDER-AMT  PIC S9(05)V99 COMP-3.
           05  PIR-ERROR-MSG        PIC X(80).

Include proper naming conventions, type mappings, constraints, descriptions, and examples.

Exercise 13: REDEFINES Resolution

Given the following copybook with REDEFINES, design an OpenAPI schema that handles both record types:

       01  ACCT-RECORD.
           05  ACCT-TYPE            PIC X(01).
              88  ACCT-PERSONAL     VALUE 'P'.
              88  ACCT-BUSINESS     VALUE 'B'.
           05  ACCT-PERSONAL-DATA REDEFINES ACCT-DATA.
               10  ACCT-FIRST-NAME PIC X(30).
               10  ACCT-LAST-NAME  PIC X(30).
               10  ACCT-SSN        PIC 9(09).
               10  FILLER          PIC X(31).
           05  ACCT-BUSINESS-DATA REDEFINES ACCT-DATA.
               10  ACCT-BUS-NAME   PIC X(60).
               10  ACCT-TAX-ID     PIC X(10).
               10  ACCT-BUS-TYPE   PIC X(20).
               10  FILLER          PIC X(10).

Use the discriminated union approach with oneOf in the OpenAPI schema.

Exercise 14: HTTP Status Code Mapping

Create a complete mapping table for the following COBOL response codes from a funds transfer program. For each mapping, provide the HTTP status code, the JSON error response body, and the consumer-facing error message (no internal details):

Exercise 15: Pagination Design

Design an OpenAPI specification for a paginated transaction history endpoint (GET /api/v1/accounts/{id}/transactions). Support: - Page-based pagination with page and pageSize query parameters - Date range filtering with fromDate and toDate query parameters - Sorting by date or amount with sortBy and sortOrder parameters - Response metadata including totalRecords, totalPages, currentPage - Navigation links (self, next, previous, first, last)

Write the complete OpenAPI path definition including all parameters, response schemas, and example values.

Exercise 16: API Naming Convention Document

Create an API naming convention document for your mainframe API program. Cover: - URL path structure and resource naming - JSON field naming (camelCase rules, abbreviation expansion) - Date/time format standards - Currency/amount format standards - Enumeration value standards - Error response structure - Versioning format

Provide at least three examples of "wrong" naming from raw COBOL field names and the "right" API-friendly alternatives.

Section 21.4 — API Mediation Layer

Exercise 17: Gateway Topology Design

Design an API gateway topology for a mainframe shop with: - Two z/OS LPARs in a production sysplex - One z/OS LPAR in a disaster recovery site - z/OS Connect running on all three LPARs - External API consumers (partner banks) and internal consumers (web applications) - Regulatory requirement that external traffic never directly reaches the mainframe

Draw the topology including all network zones, load balancers, gateways, and z/OS Connect instances. Specify which components need to be redundant.

Exercise 18: Service Discovery Configuration

Write the Zowe API ML discovery service registration YAML for three z/OS Connect instances serving the same banking API. Each instance runs on a different LPAR. Configure: - Service ID and metadata - Health check URLs - Gateway routing paths - Load balancing weight (LPAR A: 40%, LPAR B: 40%, LPAR C: 20% — DR site)

Exercise 19: Gateway Timeout Analysis

A COBOL program has the following performance profile: - p50: 150ms - p75: 250ms - p90: 500ms - p95: 800ms - p99: 2,500ms - p99.9: 8,000ms

Set the API gateway timeout and explain your reasoning. Consider: What happens if the timeout is too short? Too long? What's the business impact of each?

Exercise 20: Zowe API ML vs. API Connect

Create a comparison matrix for Zowe API ML and IBM API Connect across the following dimensions: - Cost (license, infrastructure, operations) - z/OS integration depth - Developer portal capabilities - Analytics and monitoring - Multi-platform support (can it manage non-mainframe APIs too?) - Enterprise readiness (SSO, LDAP, audit) - Community and support

Recommend which solution (or combination) is appropriate for: (a) a small mainframe shop with 10 APIs, (b) a large enterprise with 200+ mainframe APIs and 500+ cloud APIs.

Section 21.5 — API Management

Exercise 21: Rate Limiting Policy Design

Design a rate limiting policy for a banking API with three consumer tiers:

• Bronze (external partners, limited SLA): 50 requests/minute
• Silver (premium partners, standard SLA): 500 requests/minute
• Gold (internal services, full SLA): 5,000 requests/minute

For each tier, specify: - Requests per minute and burst limit - What happens when the limit is exceeded (response code, headers, retry guidance) - How the consumer upgrades to a higher tier - Monitoring and alerting thresholds (e.g., alert when a consumer reaches 80% of limit)

Exercise 22: API Analytics Dashboard

Design a monitoring dashboard for the banking API. Specify: - Five key metrics with their formulas and data sources - Three real-time alerts with trigger conditions and escalation procedures - Two capacity planning reports (weekly and monthly) - One consumer health report showing per-consumer usage patterns

Sketch the dashboard layout (text-based wireframe is fine).

Exercise 23: Developer Portal Content

Write the "Getting Started" page for SecureFirst's banking API developer portal. Include: - Prerequisites (what does a developer need before they can call the API?) - Authentication setup (step-by-step OAuth2 flow) - First API call (complete curl command with explanation) - Error handling (common errors and what to do about them) - Rate limits (what they are, how to monitor, what to do when throttled) - Support (how to get help)

Exercise 24: API Versioning Scenario

SecureFirst needs to make the following changes to the account inquiry API: a) Add an optional email field to the response b) Change the balance field from number type to string type (for precision) c) Remove the deprecated legacyAccountCode field d) Rename accountHolderName to primaryAccountHolder

For each change, determine whether it's a breaking change requiring a new version or a non-breaking change. Explain your reasoning and describe the migration path for each breaking change.

Section 21.6 — Security

Exercise 25: OAuth2 Flow Design

Design the complete OAuth2 flow for a partner bank that needs to call SecureFirst's fund transfer API. Specify: - Grant type (and why) - Token endpoint and required parameters - Token lifetime and refresh strategy - Scopes required for fund transfer vs. inquiry - Token validation steps at the API gateway - RACF user ID mapping strategy

Exercise 26: RACF Profile Design

Design RACF resource profiles for three API consumer roles: - Read-only consumer (can query accounts and transactions) - Transactional consumer (can also initiate transfers) - Administrative consumer (can also manage accounts)

For each role, specify the RACF user ID, group connections, CICS transaction authority, VSAM file access, and DB2 privileges. Use proper RACF command syntax.

Exercise 27: Security Incident Response

Write an incident response playbook for the following scenario: your API monitoring detects that a consumer's API key has been used from an unauthorized IP address range, and the calls are targeting the fund transfer endpoint at 10x the normal rate.

Include: detection, containment, investigation, remediation, communication, and post-incident review steps. Specify who is notified, what actions are taken, and in what order.

Exercise 28: mTLS Configuration

Write the configuration for mutual TLS between a partner bank's system and your API gateway. Include: - Certificate requirements (CA, key length, SAN, validity period) - Trust store configuration on both sides - Certificate rotation procedure - Fallback procedure if a certificate expires unexpectedly

Section 21.7 — Lifecycle and Governance

Exercise 29: API Governance Framework

Design an API governance framework for a mainframe shop that's exposing its first 20 APIs. Define: - Roles and responsibilities (who approves API designs? who manages the gateway? who owns the developer portal?) - Design review process (what's reviewed? by whom? what are the approval criteria?) - Change management process (how are API changes proposed, reviewed, approved, and deployed?) - Quality gates (what must pass before an API goes to production?) - Metrics and reporting (what's measured? how often? who sees the reports?)

Exercise 30: API Deprecation Plan

Write a deprecation plan for SecureFirst's v1 policy inquiry API. The v2 API has been available for 3 months. The v1 API still has 12 active consumers. Your plan must include: - Timeline with specific dates and milestones - Consumer communication strategy (who, what, when, how) - Technical implementation (deprecation headers, monitoring, traffic migration) - Escalation procedure (what if a consumer can't migrate by the deadline?) - Rollback plan (what if you need to bring v1 back after retirement?)

Integration and Synthesis

Exercise 31: End-to-End API Design

Design a complete API for a new SecureFirst service: real-time claims status inquiry. The COBOL program CLMSSTS accepts a claim number and returns claim details including status, dates, amounts, and adjuster information.

Deliver: a) COBOL copybook for request and response b) OpenAPI 3.0 specification c) z/OS Connect service archive configuration d) API gateway routing configuration e) Security requirements f) Rate limiting policy g) SLA definition

Exercise 32: Troubleshooting Scenarios

Diagnose and resolve each of the following issues:

a) API returns 200 OK but the balance field is always 0.00 for accounts with balances over $10 billion b) API response times spike from 200ms to 5,000ms every day at 2 PM c) One consumer's API calls intermittently return 503 while other consumers work fine d) The same API call returns different results when routed to different CICS regions e) After deploying a new service archive, all requests return 500 with no error detail in logs

Exercise 33: Migration Planning

CNB wants to migrate from their current screen-scraping integration (a middleware tool that logs into 3270 sessions and scrapes transaction data) to an API-based integration. The screen-scraping tool handles 15 different CICS transactions.

Create a phased migration plan: - Phase 1: Identify and prioritize transactions for API exposure - Phase 2: Build and test APIs (with parallel running) - Phase 3: Migrate consumers from screen-scraping to APIs - Phase 4: Decommission screen-scraping infrastructure

Include risk mitigation, rollback procedures, and success criteria for each phase.