Chapter 21: Further Reading

IBM Documentation

z/OS Connect Enterprise Edition

  • IBM z/OS Connect EE Documentation — The complete reference for z/OS Connect EE installation, configuration, and administration. Start with the "Getting Started" section, then read "Creating APIs and services" for the hands-on workflow. Available at the IBM Documentation site under z/OS Connect EE.
  • z/OS Connect EE API Toolkit User Guide — Step-by-step guide to using the Eclipse-based API toolkit for creating service archives, mapping COBOL copybooks to JSON schemas, and deploying services. Essential for the practitioner building their first APIs.
  • IBM Redbook: z/OS Connect Enterprise Edition V3 (SG24-8492) — Comprehensive technical guide with worked examples, architecture patterns, and best practices. Chapter 5 on CICS service providers and Chapter 7 on security are particularly relevant to this chapter.
  • IBM Redbook: Exposing Mainframe Data as APIs with z/OS Connect (REDP-5553) — A focused redpaper on the data mapping challenge, including COMP-3 handling, REDEFINES resolution, and character encoding. Shorter and more targeted than the full Redbook.

CICS Integration

  • CICS Transaction Server Documentation: Web Services — Reference for CICS web services support, including IPIC connections used by z/OS Connect, channels and containers, and the CICS web services pipeline. Useful for understanding what's happening on the CICS side of the API call.
  • IBM Redbook: CICS and z/OS Connect EE (SG24-8427) — Detailed guide to the CICS service provider in z/OS Connect, including COMMAREA vs. channel-based services, connection pooling, and workload management.

API Connect

  • IBM API Connect Documentation — Complete reference for API Connect, including the API Manager, Developer Portal, Gateway, and Analytics components. The sections on "Mainframe APIs" and "z/OS Connect integration" are directly relevant.
  • IBM Redbook: API Economy with IBM API Connect (SG24-8430) — Business and technical guide to building an API economy. While not mainframe-specific, the chapters on API lifecycle management, monetization, and developer experience apply directly.

Zowe and Open Source

Zowe API Mediation Layer

  • Zowe Documentation: API Mediation Layer — Official documentation for Zowe API ML, including the API Gateway, Discovery Service, and API Catalog. The "Getting Started" tutorial walks through deploying all three components. Available at docs.zowe.org.
  • Zowe GitHub Repository — Source code for the Zowe API Mediation Layer. Useful for understanding the implementation, contributing fixes, and building custom extensions. See the api-mediation directory.
  • Zowe API ML Architecture Deep Dive — Technical blog series by the Zowe community explaining the gateway's routing logic, the discovery service's health checking, and the catalog's OpenAPI aggregation. Search the Zowe blog at medium.com/zowe.

OpenAPI Specification

  • OpenAPI Specification 3.0 (spec.openapis.org) — The official specification document. Read sections 4.7 (Schema Object) and 4.8 (Paths Object) carefully — they define the JSON schema constraints you'll use to represent COBOL data structures.
  • OpenAPI Specification 3.1 — The latest version, which aligns JSON Schema support with JSON Schema 2020-12. If your organization is adopting 3.1, note the changes to nullable handling and discriminator behavior.
  • Swagger Editor (editor.swagger.io) — Online tool for writing and validating OpenAPI specifications. Useful for designing your COBOL-backed APIs before implementing them in z/OS Connect.

Books

API Design

  • Lauret, Arnaud. "The Design of Web APIs." Manning, 2019. — The best single book on API design principles. Covers resource modeling, naming, versioning, error handling, and documentation. Not mainframe-specific, but every principle applies. Read Chapters 3-7 before designing your first mainframe API.
  • Higginbotham, James. "Principles of Web API Design." Addison-Wesley, 2022. — More advanced than Lauret, with deeper coverage of API lifecycle management, breaking changes, and API governance. The chapter on "API-as-a-Product" directly supports Section 21.7.
  • Sturgeon, Phil. "Build APIs You Won't Hate." LeanPub, 2015 (updated 2022). — Practical, opinionated guide to building REST APIs. The tone is irreverent but the advice is solid. Particularly useful for the common mistakes section — many apply to mainframe APIs.

Mainframe Modernization

  • Adshead, Dale, et al. "Modernizing Mainframe Applications." IBM Press, 2023. — Comprehensive guide to mainframe modernization strategies, including API-first, strangler fig, and event-driven patterns. Chapter 8 on API exposure is the most directly relevant to this chapter.
  • Kohnke, Oliver, and Matthias Kross. "The Mainframe Developer's Guide to Modernization." Apress, 2022. — Written for COBOL developers learning modern integration patterns. The chapters on REST, JSON, and z/OS Connect are accessible and practical.

API Security

  • Madden, Neil. "API Security in Action." Manning, 2020. — Thorough treatment of API security including OAuth 2.0, JWT, mTLS, and rate limiting. Chapter 11 on token-based authentication and Chapter 13 on securing microservices apply directly to mainframe API security.
  • NIST Special Publication 800-204: Security Strategies for Microservices-based Application Systems. — Federal government standard for API security. Required reading if you're building APIs in a government context (like the Federal Benefits case study). Available free at csrc.nist.gov.

Articles and Papers

Architecture Patterns

  • Richardson, Chris. "API Gateway Pattern." microservices.io. — Clear explanation of the API gateway pattern with diagrams and trade-off analysis. While written for microservices, the pattern applies identically to mainframe APIs.
  • Newman, Sam. "Building Microservices, 2nd Edition." O'Reilly, 2021. — Chapter 4 on API design and Chapter 13 on "The Strangler Fig Application" pattern are relevant. The strangler fig pattern is how many organizations incrementally expose mainframe services as APIs.
  • Fowler, Martin. "API Gateway." martinfowler.com, 2023. — Concise overview of API gateway patterns, including edge gateway, BFF (Backend for Frontend), and API composition. Useful for deciding how to structure your gateway layer.

Mainframe APIs in Practice

  • IBM Developer: "Create a RESTful API from a COBOL Program" — Step-by-step tutorial with screenshots showing the complete flow from COBOL copybook to deployed API. The best practical getting-started resource.
  • Broadcom: "Zowe API Mediation Layer: Getting Started" — Tutorial for deploying Zowe API ML with z/OS Connect as a registered service. Includes gateway configuration, discovery service setup, and API catalog population.

API Governance

  • Mulesoft: "API-led Connectivity" whitepaper. — Framework for organizing APIs into system, process, and experience layers. While vendor-specific in implementation, the three-layer model maps well to the mainframe architecture: system APIs (z/OS Connect), process APIs (gateway), and experience APIs (consumer-facing).
  • Postman: "2024 State of the API Report" — Annual survey of API practitioners covering design practices, governance, tooling, and challenges. Useful for benchmarking your organization's API maturity against industry norms.

Standards

  • OpenAPI Specification 3.0.3 — The version most widely supported by tools and recommended for new mainframe API projects.
  • JSON Schema (2020-12) — The schema language used within OpenAPI for defining request/response structures. Understanding JSON Schema is essential for accurately representing COBOL data types.
  • RFC 6749: The OAuth 2.0 Authorization Framework — The foundational OAuth 2.0 specification. Read Sections 1-4 for the core concepts.
  • RFC 7519: JSON Web Token (JWT) — JWT specification. Understand the header, payload, and signature structure.
  • RFC 8594: The Sunset HTTP Header Field — Defines the Sunset header used in API deprecation. Short and worth reading in full.
  • RFC 6585: Additional HTTP Status Codes — Defines 429 Too Many Requests used for rate limiting.

Tools

  • z/OS Connect EE API Toolkit — Eclipse-based IDE plugin for creating service archives. Download from IBM.
  • zconbt — Command-line tool for building service archives without Eclipse. Useful for CI/CD pipelines.
  • Swagger UI — Interactive API documentation renderer. Embedded in Zowe API Catalog and available standalone.
  • Postman — API testing tool. Essential for manually testing your mainframe APIs during development.
  • Dredd — API contract testing tool that validates an API against its OpenAPI specification. Catches discrepancies between your spec and your implementation.
  • OWASP ZAP — Open-source security scanner for APIs. Run it against your staging APIs to find security vulnerabilities before production deployment.
  • jq — Command-line JSON processor. Invaluable for inspecting and transforming API responses during debugging.