Calling external APIs from COBOL

Three common ways

• z/OS Connect API requester — generates COBOL copybooks from the other service's OpenAPI document. Your program fills in a structure and makes a call; z/OS Connect handles HTTP and JSON.
• CICS web API — a CICS program opens a connection with EXEC CICS WEB OPEN, sends the request with WEB CONVERSE, and reads the response.
• COBOL JSON statements — Enterprise COBOL can build JSON from a data structure with JSON GENERATE and read it back with JSON PARSE, whatever transport you use.

      * WS-FRAUD-REQ holds account id and amount
           JSON GENERATE WS-JSON-OUT FROM WS-FRAUD-REQ
               COUNT IN WS-JSON-LEN
               NAME OF ACCT-ID IS 'accountId'
               NAME OF TXN-AMOUNT IS 'amount'
               ON EXCEPTION
                   PERFORM 9000-JSON-ERROR
           END-JSON

Plan for the other side failing

The external service is outside your control. It will sometimes be slow or unavailable, and your transaction must still behave well.

• Set a timeout. A CICS transaction waiting forever holds resources and can affect other users.
• Decide the fallback. If the fraud check is down, do you refuse the payment, allow it under a limit, or queue it for review? This is a business decision — get it written down.
• Retry carefully. Only retry calls that are safe to repeat (idempotent). Retrying a payment could pay twice.
• Log enough to trace. Record a correlation ID, the status code and the time taken, never the full personal data.