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.