Reverse API
Overview
We primarily use APIs to get data from a backend system to an external client. For example: a mobile app to open a bank account would use an API to send data provided by users to a mainframe RPC program that would actually perform the action of opening the account.
But what if a mainframe program requires information that resides outside of the mainframe?
Some use cases:
- Mainframe requires real-time exchange rate information from an external system/provider.
- Some mainframe programs were migrated to a cloud-based environment, while the remaining mainframe programs still need to use the migrated programs.
The Reverse-API is an HTTP/HTTPS server that receives a mainframe Request Buffer that invokes the appropriate Hub Project method (according to the URL called by the mainframe). The project method is then executed and its response is sent back to the mainframe as a buffer.
Our server acts as a proxy for the mainframe, calling the external service in lieu of the mainframe and returning the results, thus allowing mainframe programs to communicate with external REST APIs, other systems, and any backend system for which OpenLegacy has a connector.
The Hub will create that server for you, ensure that all the deployed methods support application/octet-stream, and make sure that the models sent and received by the mainframe align with the Project methods by enabling users to generate Cobol clients. These clients can be compiled on the mainframe with very little editing required. Once compiled, other programs can make calls to these clients and utilize them for their own needs.
You can have a service up and running in a matter of minutes.
The diagram below illustrates this Reverse-API architecture:
A simple (but common) use case walkthrough:
On the Hub or using the CLI
- Create a REST OpenAPI module.
- Add assets by providing the Rest API OpenAPI spec.
- Test the assets and verify everything is working properly.
- Create a new project and associate the newly created module with it.
- Change the Use Case to Reverse API.
- Create a project contract by selecting the Auto-Generated option. This option ensures that the contract is generated configured for Reverse API.
- The methods are generated for each asset.
- Deploy the project (Low Code / No Code) by clicking on the
Deploy button.
- At this point, you can simulate a Mainframe call by opening the Swagger page and providing the method with a Binary file to simulate a mainframe request.
- Click on Configure ReverseAPI to configure the contract.
- The Configure ReverseAPI window opens.
- The Base Path specifies the configuration of the deployed service on the machine. For example, if it is deployed on the xxx.xxx.xxx.xxx machine, then to call the service you would reference:
xxx.xxx.xxx.xxx/<Base Path> - The Client Type specifies the client architecture. The current types are mainframe (Z/OS or Z/VSE) and AS\400 (COBOL or RPG).
- The Base Path specifies the configuration of the deployed service on the machine. For example, if it is deployed on the xxx.xxx.xxx.xxx machine, then to call the service you would reference:
- If a Z/OS Client Type is selected, you must also specify the URI Map name in the mainframe that holds the URL for OpenLegacy deployed service.
- If a Z/VSE or AS400 Client Type is selected, you must also specify the Server URL for the OpenLegacy deployed service.
- Click Save to save the ReverseAPI contract configuration.
Field Buffer Sizes in Client Generation
Because Legacy systems rely on fixed buffer sizes for input fields — sizes that depend on the field’s data type — OpenLegacy assigns default buffer values designed to cover most common cases.
In some scenarios, an executed asset may contain fields that vary in length.
For example, a balance field might hold values such as 153.26 or 123,456,433.34.
While the asset itself may be agnostic to the exact field size, a COBOL client requires a defined field length at generation time.
To simplify this process and avoid manually setting sizes for every field, OpenLegacy provides the following default buffer sizes:
| Data Type | Default Size | Notes |
|---|---|---|
| String | 50 | Applies to character fields |
| Numeric | 18 | Includes 2 decimal digits for Double types |
| Collection | 20 | Default number of items in a collection |
Users can override these defaults in two ways:
- Per field: by setting a custom length for a specific input or output field.
- Globally: by updating the default values in the method’s Configure Reverse API window.
- You may need to edit the client to change the default settings for the fields.
- Click Generate Cobol.
- A zip file of the Cobol client is downloaded.
- The zip file consists of Cobol client corresponding to each of the methods.
In case of COBOL based clients an additional copybook that is referenced by the clients and contain connection information to the deployed Project's URL, will also be generated.
IDENTIFICATION DIVISION.
* Please Provide a valid PROGRAM-ID
PROGRAM-ID. GEOFRWRD.
********************************************************
* OpenLegacy Hub CICS Client *
********************************************************
* Licensed Materials - Property of OpenLegacy *
* "Restricted Materials of OpenLegacy" *
* (C) Copyright OpenLegacy 2015-2025 *
********************************************************
* OpenLegacy Core Version: 5.0.114
* OpenLegacy DTF Version: 3.0.19
********************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY OLAPICPY.
LINKAGE SECTION.
01 DFHCOMMAREA.
03 INPUT-INPUT.
05 ACCESS-KEY PIC X(50).
05 QUERY PIC X(50).
03 ACCOUNTS-OUTPUT-200.
05 DATA2 OCCURS 20 TIMES.
07 LATITUDE PIC 9(18).
07 LONGITUDE PIC 9(18).
07 TYPE2 PIC X(50).
07 NAME PIC X(50).
07 NUMBER2 PIC X(50).
07 POSTAL-CODE PIC X(50).
07 STREET PIC X(50).
07 CONFIDENCE PIC 9(18).
07 REGION PIC X(50).
07 REGION-CODE PIC X(50).
07 COUNTY PIC X(50).
07 LOCALITY PIC X(50).
07 ADMINISTRATIVE-AREA PIC X(50).
07 NEIGHBOURHOOD PIC X(50).
07 COUNTRY PIC X(50).
07 COUNTRY-CODE PIC X(50).
07 CONTINENT PIC X(50).
07 LABEL2 PIC X(50).
PROCEDURE DIVISION.
MOVE "/geo-forward" TO OLREVAPI-SERVICE-PATH.
CALL OLREVAPI USING
BY REFERENCE OLREVAPI-CALL-VARS
BY REFERENCE INPUT-INPUT
BY VALUE LENGTH OF INPUT-INPUT
BY REFERENCE ACCOUNTS-OUTPUT-200
BY VALUE LENGTH OF ACCOUNTS-OUTPUT-200
RETURNING OLREVAPI-RESULT.
END-PROGRAM.
EXEC CICS RETURN END-EXEC.
END PROGRAM GEOFRWRD. IDENTIFICATION DIVISION.
PROGRAM-ID. GEOFRWRD.
* OpenLegacy API Caller - z/VSE Client Example for CICS *
*****************************************************************
*****************************************************************
* *
* Licensed Materials - Property of OpenLegacy *
* *
* "Restricted Materials of OpenLegacy" *
* *
* (C) Copyright OpenLegacy 2015-2025 *
* *
*****************************************************************
* OpenLegacy Core Version: 5.0.114
* OpenLegacy DTF Version: 3.0.19
********************************************************
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
**************************************************************
* Constants
**************************************************************
01 WS-EYE PIC X(16)
VALUE '-WORKINGSTORAGE-'.
01 WS-EYE2 PIC X(16)
VALUE '-VSEHTTPT -'.
**************************************************************
* Local variables
**************************************************************
01 LOCAL-VARIABLES.
03 RESP PIC S9(8) COMP.
03 RESP2 PIC S9(8) COMP.
**************************************************************
* Error Messages
**************************************************************
01 OUTPUT-DATA.
02 OUTPUT-MESSGAE PIC X(79).
02 OUT-ERROR REDEFINES OUTPUT-MESSGAE.
03 OUT-ERROR-MSG PIC X(19).
03 OUT-RETCODE PIC X(60).
**************************************************************
* Variables required to LINK to program IESHTTPC
**************************************************************
******************************
* Http Client Request *
******************************
01 HTTP-REQ-EYE PIC X(16) VALUE '****HTTP-REQ****'.
01 HTTP-REQ.
02 AREALEN PIC 9(9) BINARY.
02 URL USAGE IS POINTER.
02 URLLEN PIC 9(9) BINARY.
02 REQUEST PIC 9(9) BINARY.
02 USERAGENT USAGE IS POINTER.
02 USERAGENTLEN PIC 9(9) BINARY.
02 ACCEPTS USAGE IS POINTER.
02 ACCEPTSLEN PIC 9(9) BINARY.
02 USERDATA USAGE IS POINTER.
02 POSTHANDLER PIC 9(9) BINARY.
02 POSTDATA USAGE IS POINTER.
02 POSTLENGTH PIC 9(9) BINARY.
02 POSTCONTENTTYPE USAGE IS POINTER.
02 PCONTENTTYPELEN PIC 9(9) BINARY.
02 HANDLER PIC 9(9) BINARY.
02 DATA1 USAGE IS POINTER.
02 LENGTH1 PIC 9(9) BINARY.
02 CONTENTTYPE USAGE IS POINTER.
02 CONTENTTYPELEN PIC 9(9) BINARY.
02 RETCODE USAGE IS POINTER.
02 RETCODELEN PIC 9(9) BINARY.
02 PROXYTYPE PIC 9(9) BINARY.
02 PROXY USAGE IS POINTER.
02 PROXYLEN PIC 9(9) BINARY.
02 PROXYPORT PIC 9(9) BINARY.
02 USER USAGE IS POINTER.
02 USERLEN PIC 9(9) BINARY.
02 PASSWORD1 USAGE IS POINTER.
02 PASSWORDLEN PIC 9(9) BINARY.
02 ASCIICP USAGE IS POINTER.
02 ASCIICPLEN PIC 9(9) BINARY.
02 EBCDICCP USAGE IS POINTER.
02 EBCDICCPLEN PIC 9(9) BINARY.
02 HDRLINE USAGE IS POINTER.
02 HDRLINELEN PIC 9(9) BINARY.
02 NEWLOCATION USAGE IS POINTER.
02 LEWLOCATIONLEN PIC 9(9) BINARY.
02 KEYRINGLIBLEN PIC 9(9) BINARY.
02 KEYRINGLIB USAGE IS POINTER.
02 KEYNAME USAGE IS POINTER.
02 KEYNAMELEN PIC 9(9) BINARY.
02 CIPERSPECS USAGE IS POINTER.
02 CIPERSPECSLEN PIC 9(9) BINARY.
02 SESSTIMEOUT PIC 9(9) BINARY.
02 AUTHUSER USAGE IS POINTER.
02 AUTHUSERLEN PIC 9(9) BINARY.
02 AUTHPWD USAGE IS POINTER.
02 AUTHPWDLEN PIC 9(9) BINARY.
02 SSLTYPE USAGE IS POINTER.
02 SSLTYPELEN PIC 9(9) BINARY.
******************************
* Handler parameter area *
******************************
01 HANDLER-PARM.
02 HTTPREQ USAGE IS POINTER.
02 BUFFER USAGE IS POINTER.
02 LENGTH2 PIC 9(9) BINARY.
******************************
* Values for HTTP request *
******************************
01 HTTP-GET PIC 9(9) BINARY VALUE 1.
01 HTTP-POST PIC 9(9) BINARY VALUE 2.
01 HTTP-GET-BINARY PIC 9(9) BINARY VALUE 3.
01 HTTP-POST-BINARY PIC 9(9) BINARY VALUE 4.
01 HTTP-GET-TEXT PIC 9(9) BINARY VALUE 5.
01 HTTP-POST-TEXT PIC 9(9) BINARY VALUE 6.
******************************
* Values for handler type *
******************************
01 HTTP-HANDLER-BUFFER PIC 9(9) BINARY VALUE 1.
01 HTTP-HANDLER-FUNCTION PIC 9(9) BINARY VALUE 2.
01 HTTP-HANDLER-PROGRAM PIC 9(9) BINARY VALUE 3.
******************************
* Values for proxy type *
******************************
01 HTTP-TYPE-DIRECT PIC 9(9) BINARY VALUE 0.
01 HTTP-TYPE-PROXY PIC 9(9) BINARY VALUE 1.
01 HTTP-TYPE-SOCKS4 PIC 9(9) BINARY VALUE 2.
01 HTTP-TYPE-SOCKS5 PIC 9(9) BINARY VALUE 3.
******************************
* Return Codes *
******************************
01 HTTPERR-NO-ERROR PIC 9(9) BINARY VALUE 0.
01 HTTPERR-INVALID-PARAM PIC 9(9) BINARY VALUE 1.
01 HTTPERR-NULL-POINTER PIC 9(9) BINARY VALUE 2.
01 HTTPERR-NETWORK-ERR PIC 9(9) BINARY VALUE 3.
01 HTTPERR-URL-ERROR PIC 9(9) BINARY VALUE 4.
01 HTTPERR-UNKNOWN-HOST PIC 9(9) BINARY VALUE 5.
01 HTTPERR-CONNECT-FAILED PIC 9(9) BINARY VALUE 6.
01 HTTPERR-CONNECTION-BROKEN PIC 9(9) BINARY VALUE 7.
01 HTTPERR-CONNECTION-CLOSED PIC 9(9) BINARY VALUE 8.
01 HTTPERR-INVALID-RESP PIC 9(9) BINARY VALUE 9.
01 HTTPERR-NOT-ALLOWED PIC 9(9) BINARY VALUE 10.
01 HTTPERR-CODEPAGE PIC 9(9) BINARY VALUE 11.
01 HTTPERR-SSL-INIT PIC 9(9) BINARY VALUE 12.
01 HTTPERR-SSL-HANDSHAKE PIC 9(9) BINARY VALUE 13.
01 HTTPERR-NO-MEMORY PIC 9(9) BINARY VALUE 14.
01 HTTPERR-COMMAREA-LEN PIC 9(9) BINARY VALUE 15.
01 HTTPERR-PARAM-LEN PIC 9(9) BINARY VALUE 16.
**************************************************************
* LINKAGE SECTION (Getmained)
**************************************************************
LINKAGE SECTION.
01 GETM-VARIABLES.
03 URLX PIC X(33).
03 ACCEPTSX PIC X(8).
03 POSTDATAX.
05 HTTP-REQUEST.
07 BODY-PARAMS.
09 INPUT-INPUT.
11 ACCESS-KEY PIC X(50).
11 QUERY PIC X(50).
03 POSTCONTENTTYPEX PIC X(24).
03 DATA1X.
05 HTTP-RESPONSE.
07 STATUS-CODE PIC 9(3).
07 STATUS-MESSAGE PIC X(256).
07 RESPONSES.
09 RESPONSE-200.
11 RESPONSE-200-BODY.
13 ACCOUNTS-OUTPUT-200.
15 DATA2 OCCURS 20 TIMES.
17 LATITUDE PIC 9(18).
17 LONGITUDE PIC 9(18).
17 TYPE2 PIC X(50).
17 NAME PIC X(50).
17 NUMBER2 PIC X(50).
17 POSTAL-CODE PIC X(50).
17 STREET PIC X(50).
17 CONFIDENCE PIC 9(18).
17 REGION PIC X(50).
17 REGION-CODE PIC X(50).
17 COUNTY PIC X(50).
17 LOCALITY PIC X(50).
17 ADMINISTRATIVE-AREA PIC X(50).
17 NEIGHBOURHOOD PIC X(50).
17 COUNTRY PIC X(50).
17 COUNTRY-CODE PIC X(50).
17 CONTINENT PIC X(50).
17 LABEL2 PIC X(50).
03 CONTENTTYPEX PIC X(24).
03 RETCODEX PIC X(100).
03 ASCIICPX PIC X(8).
03 EBCDICCPX PIC X(8).
**************************************************************
* PROGRAM START
**************************************************************
PROCEDURE DIVISION.
MOVE 'VSEHTTPT STARTED' TO OUTPUT-DATA.
EXEC CICS WRITE OPERATOR TEXT(OUTPUT-DATA) END-EXEC.
EXEC CICS GETMAIN FLENGTH(LENGTH OF GETM-VARIABLES)
SET(ADDRESS OF GETM-VARIABLES)
END-EXEC.
MOVE LOW-VALUES TO GETM-VARIABLES.
* -------------------------------------------------------
* Prepare HTTP variables
* -------------------------------------------------------
* ----+----1----+----2----+----3----+----4----+----
MOVE 'http://server.fff.com/geo-forward' TO URLX.
MOVE 'text/xml' TO ACCEPTSX.
MOVE 'application/octet-stream' TO POSTCONTENTTYPEX.
MOVE SPACES TO DATA1X.
MOVE 'application/octet-stream' TO CONTENTTYPEX.
MOVE SPACES TO RETCODEX.
* MOVE 'IBM-1047' TO ASCIICPX.
* MOVE 'IBM-1047' TO EBCDICCPX.
* -------------------------------------------------------
* Prepare Payload to send
* -------------------------------------------------------
* AUTO-GENERATED BLOCK - PROGRAM LOGIC STARTS HERE *****
* AUTO-GENERATED BLOCK - PROGRAM LOGIC ENDS HERE *****
* -------------------------------------------------------
* Fixed settings
* -------------------------------------------------------
MOVE LOW-VALUES TO HTTP-REQ.
MOVE LENGTH OF HTTP-REQ TO AREALEN.
MOVE HTTP-POST-BINARY TO REQUEST.
SET URL TO ADDRESS OF URLX.
MOVE LENGTH OF URLX TO URLLEN.
SET ACCEPTS TO ADDRESS OF ACCEPTSX.
MOVE LENGTH OF ACCEPTSX TO ACCEPTSLEN.
*
* Prepare the POST releated areas
*
MOVE HTTP-HANDLER-BUFFER TO POSTHANDLER.
SET POSTDATA TO ADDRESS OF POSTDATAX.
MOVE LENGTH OF POSTDATAX TO POSTLENGTH.
SET POSTCONTENTTYPE TO ADDRESS OF POSTCONTENTTYPEX.
MOVE LENGTH OF POSTCONTENTTYPEX TO PCONTENTTYPELEN.
*
* Prepare the answe releated areas
*
MOVE HTTP-HANDLER-BUFFER TO HANDLER.
SET DATA1 TO ADDRESS OF DATA1X.
MOVE LENGTH OF DATA1X TO LENGTH1.
SET CONTENTTYPE TO ADDRESS OF CONTENTTYPEX.
MOVE LENGTH OF CONTENTTYPEX TO CONTENTTYPELEN.
*
* ------------------------------------------------
* Uncomment if code pages conversions are needed
* Not needed for OpenLegacy
*
* SET ASCIICP TO ADDRESS OF ASCIICPX.
* MOVE LENGTH OF ASCIICPX TO ASCIICPLEN.
*
* SET EBCDICCP TO ADDRESS OF EBCDICCPX.
* MOVE LENGTH OF EBCDICCPX TO EBCDICCPLEN.
* ------------------------------------------------
*
SET RETCODE TO ADDRESS OF RETCODEX.
MOVE LENGTH OF RETCODEX TO RETCODELEN.
* -------------------------------------------------------
* LINK to the z/VSE HTTP program issuer
* -------------------------------------------------------
EXEC CICS LINK
PROGRAM('IESHTTPC')
COMMAREA(HTTP-REQ)
LENGTH(LENGTH OF HTTP-REQ)
RESP(RESP)
RESP2(RESP2)
END-EXEC.
* -------------------------------------------------------
* Process answer
* -------------------------------------------------------
MOVE 'VSEHTTPT RETCODE = ' TO OUT-ERROR-MSG.
MOVE RETCODEX TO OUT-RETCODE.
EXEC CICS SEND FROM(OUTPUT-DATA)
LENGTH(LENGTH OF OUTPUT-DATA)
ERASE NOHANDLE
END-EXEC.
MOVE 'VSEHTTPT ENDED' TO OUTPUT-DATA.
EXEC CICS WRITE OPERATOR TEXT(OUTPUT-DATA) END-EXEC.
* -------------------------------------------------------
* End
* -------------------------------------------------------
EXEC CICS RETURN END-EXEC.
IDENTIFICATION DIVISION.
PROGRAM-ID. GEOFRWRD.
********************************************************
* OpenLegacy Hub AS400 Client *
********************************************************
* Licensed Materials - Property of OpenLegacy *
* "Restricted Materials of OpenLegacy" *
* (C) Copyright OpenLegacy 2015-2025 *
********************************************************
* OpenLegacy Core Version: 5.0.114
* OpenLegacy DTF Version: 3.0.19
********************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY OLAPICPY.
LINKAGE SECTION.
01 DATA-AREA.
03 INPUT-INPUT.
05 ACCESS-KEY PIC X(50).
05 QUERY PIC X(50).
03 ACCOUNTS-OUTPUT-200.
05 DATA2 OCCURS 20 TIMES.
07 LATITUDE PIC 9(18).
07 LONGITUDE PIC 9(18).
07 TYPE2 PIC X(50).
07 NAME PIC X(50).
07 NUMBER2 PIC X(50).
07 POSTAL-CODE PIC X(50).
07 STREET PIC X(50).
07 CONFIDENCE PIC 9(18).
07 REGION PIC X(50).
07 REGION-CODE PIC X(50).
07 COUNTY PIC X(50).
07 LOCALITY PIC X(50).
07 ADMINISTRATIVE-AREA PIC X(50).
07 NEIGHBOURHOOD PIC X(50).
07 COUNTRY PIC X(50).
07 COUNTRY-CODE PIC X(50).
07 CONTINENT PIC X(50).
07 LABEL2 PIC X(50).
PROCEDURE DIVISION USING DATA-AREA.
MAIN.
* MOVE "http://server.fff.com"
* TO OLREVAPI-URL.
MOVE "/geo-forward" TO OLREVAPI-SERVICE-PATH.
CALL PROCEDURE "OLREVAPI" USING
BY REFERENCE OLREVAPI-CALL-VARS
BY REFERENCE INPUT-INPUT
BY VALUE LENGTH OF INPUT-INPUT
BY REFERENCE ACCOUNTS-OUTPUT-200
BY VALUE LENGTH OF ACCOUNTS-OUTPUT-200
RETURNING OLREVAPI-RESULT.
GO-BACK.
GOBACK.
END PROGRAM GEOFRWRD.**FREE
// ********************************************************
// * OpenLegacy Hub AS400 RPGLE Client *
// ********************************************************
// * Licensed Materials - Property of OpenLegacy *
// * "Restricted Materials of OpenLegacy" *
// * (C) Copyright OpenLegacy 2015-2025 *
// ********************************************************
// Program name: GEOFRWRD
//
// OpenLegacy Core Version: 5.0.114
// OpenLegacy DTF Version: 3.0.19
dcl-pr ol_rpg_api int(10) extproc('OL_RPG_API') opdesc;
api_caller_url varchar(1024) const options(*varsize);
api_caller_key varchar(1024) const options(*varsize);
send_buffer char(16000000) const options(*varsize);
result_buffer char(16000000) options(*varsize);
end-pr;
dcl-pr http_debug extproc('HTTP_DEBUG');
peStatus ind const;
peFilename varchar(500) const options(*nopass);
end-pr;
// ol_rpg_api result values
dcl-c APC_HTTP_SETCCSIDS_FAILED -1500;
dcl-c APC_HTTP_XPROC_FAILED -2000;
dcl-c APC_SUCCESS 1;
dcl-c APC_RESULT_BUFFER_SHORT 2;
dcl-ds request_t qualified;
dcl-ds body;
access_key char(50);
query char(50);
end-ds;
end-ds;
dcl-ds response_t qualified;
dcl-ds response_7d40df47_d07e48ea_b5965567385c1fa2;
dcl-ds body;
dcl-ds data dim(20);
latitude zoned(18:0);
longitude zoned(18:0);
type char(50);
name char(50);
number char(50);
postal_code char(50);
street char(50);
confidence zoned(18:0);
region char(50);
region_code char(50);
county char(50);
locality char(50);
administrative_area char(50);
neighbourhood char(50);
country char(50);
country_code char(50);
continent char(50);
label char(50);
end-ds;
end-ds;
end-ds;
end-ds;
dcl-pi *n;
request likeDS(request_t);
response likeDS(response_t);
end-pi;
dcl-s api_caller_url varchar(128) inz('http://server.fff.com/geo-forward');
dcl-s api_caller_key varchar(32) inz('{API_KEY}');
dcl-s api_caller_result int(10);
// This enabled HTTPApi debug mode which writes it's debug log to
// the IFS as /tmp/httpapi_debug.txt
// http_debug(*on);
api_caller_result = ol_rpg_api(api_caller_url: api_caller_key: request: response);
return;
On the Legacy Environment
- If the Program ID, Server URL, or URI Map values were not set in the Hub, edit the generated code accordingly.
- Compile the clients.
Updated about 1 month ago