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

1. Create a REST OpenAPI module.
   
2. Add assets by providing the Rest API OpenAPI spec.
   
3. Test the assets and verify everything is working properly.
4. Create a new project and associate the newly created module with it.
   
5. Change the Use Case to Reverse API.
6. Create a project contract by selecting the Auto-Generated option. This option ensures that the contract is generated configured for Reverse API.
   
7. The methods are generated for each asset.
   
8. Deploy the project (Low Code / No Code) by clicking on the Deploy button.
   1. 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.
9. Click on Configure ReverseAPI to configure the contract.
   
10. The Configure ReverseAPI window opens.
    1. 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>
    2. The Client Type specifies the client architecture. The current types are mainframe (Z/OS or Z/VSE) and AS400.
       
11. 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.
    
12. If a Z/VSE or AS400 Client Type is selected, you must also specify the Server URL for the OpenLegacy deployed service.
    
13. Click Save to save the ReverseAPI contract configuration.
14. You may need to edit the client to change the default settings for the fields.
    
15. Click Generate Cobol.
    
16. A zip file of the Cobol client is downloaded.
    
17. The zip file consists of Cobol files corresponding to each of the methods.
    

On the Mainframe

1. The generated Cobol files need to be edited.
   
   1. Change the value of PROGRAM-ID.
   2. A URI map needs to be created that would point to the deployed project’s base URL.
   3. For the generated clients, change the URIMAP value to the name of the new URI map.
2. Compile the clients.

Default Data Type Sizes

Because the mainframe is dealing with fixed buffer sizes for input fields, which are dependent on the input field data type, Open Legacy sets default values for these buffer sizes that are designed to cover most cases.

In some cases an executed asset may have fields that vary in size , for instance, a balance field may hold a 153.26 value OR 123,456,433.34 value. The Asset may be agnostic to the field size. However, when generating a COBOL client it is required to provide a field size.

To avoid having to set the field length for each and every field, OpenLegacy provides default values for these buffer sizes that are designed to cover most cases.The default sizes are:

• String - 50
• Numeric - 18
• Number of collection items - 20

The user can override this default value by setting the length on a specific input/output field OR the user may change these default values in the Method’s Configure Reverse API window: