Enhancing z/OS Connect for Dynamic API Integration with JSON Response Handling

Abstract

This document proposes an enhancement to IBM z/OS Connect to support flexible consumption of API responses in JSON format without mandating COBOL copybook regeneration for every API update. This capability aims to streamline integration efforts when partner systems update their APIs by enabling applications to handle JSON responses dynamically or consume them as plain text.

Motivation

Currently, z/OS Connect applications rely on Swagger files to generate COBOL copybooks that map JSON response variables to COBOL structures. This rigid approach creates significant overhead when partner systems frequently update their APIs, often introducing new JSON variables irrelevant to the consuming application. Despite being unnecessary, these changes necessitate regenerating and deploying new copybooks.

Partner systems have suggested adopting a universal design that allows consuming the entire JSON response as a single variable. This would decouple application logic from frequent API updates and reduce dependency on copybook regeneration.

Benefits of the Proposed Enhancement:

1. Reduced Maintenance Overhead: Eliminate frequent copybook regeneration due to irrelevant API updates.
2. Improved Agility: Enable dynamic parsing of JSON responses within applications based on specific requirements.
3. Enhanced Interoperability: Allow z/OS Connect to work seamlessly with APIs using varied response formats.
4. Simplified Partner Integration: Align with partner system expectations, enhancing collaboration and system compatibility.

Technical Proposal

Features to be Added:

1. Dynamic JSON Response Handling:
   1. Provide an option to consume the entire JSON response as a single COBOL variable (e.g., JSON_RESPONSE of type CHARACTER or similar).
   2. Applications can parse the JSON dynamically using existing COBOL JSON parsers.
2. Support for Plain Text Responses:
   1. Enable z/OS Connect to accept API responses in text/plain format, which can also be consumed as a single variable.
   2. Simplifies integration scenarios where raw response processing is preferred.

Conclusion

Enhancing z/OS Connect with dynamic JSON response handling and support for plain text responses addresses the challenges posed by frequent API updates from partner systems. This proposal aligns with modern API integration practices, reduces maintenance efforts, and fosters flexibility, ultimately improving the developer experience and operational efficiency.