The Gen 8.6 Consuming REST APIs for Java and CICS Applications feature allows your Gen applications to use functionality provided by RESTful Web Services. The purpose of this document is to help you get started using this feature by answering some of the most frequently asked questions.
In June of 2022, native support for security schemes like BasicAuth, BearerAuth, ApiKeyAuth, and OAuth2 (Client Credentials Flow) was added to the Consuming REST APIs for Java and CICS Applications feature. This article has been updated to reflect this additional functionality.
COBOL application executing on CICS
1) What is a RESTful API?
The textbook definition is a Web API (Web Service) that conforms to the REST architectural style. A good description of REST can be found here. In Gen, the Call REST statement can be used for any Web Service that communicates via HTTP and can accept or send JSON data.
2) What is the difference between publishing and consuming RESTful APIs?
3) How can I publish a REST API using Gen?
Web Services GENius, by Response Systems and available directly from Broadcom, is available for publishing REST APIs for Java and CICS applications developed in Gen. Contact your Broadcom account manager for more information or read more information here.
4) What is an OpenAPI specification?
An OpenAPI specification is a format for describing REST APIs. The OpenAPI specification allows an API developer to define:
Swagger is a good starting point for information about the OpenAPI specification.
5) How do I create an OpenAPI specification?
Some remote services provide OpenAPI specifications that can be used by Gen. For example the Swagger Pet Store (https://petstore3.swagger.io/api/v3/openapi.json) provides its specification.
If you are creating a service using Spring Boot, you can use springdoc-openapi to automatically generate the OpenAPI specification for the service. See this tutorial for more information on creating an OpenAPI specification with your code.
If you use Response Systems’ Web Services GENius to create a web service from your Gen application, the tool will create an OpenAPI specification for you.
If it is necessary to create a specification by hand, you can get directions at: Creating an OpenAPI Specification (OAS) by Hand
6) My service produces its specification in YAML. How do I convert it to JSON?
When native support for security schemes was added to the Consuming REST APIs for Java and CICS Applications feature, the Gen Toolset was also updated to support both JSON and YAML specifications. After applying PTF TSN86225, there is no longer a need to convert YAML specifications to JSON. The Gen Toolset can now process either JSON or YAML specifications.
7) What do I need to do to add Call REST functionality to my models?
Gen 8.6 Solutions and Patches contains links to download all of the Gen PTFs needed to support the Call REST functionality. The Mainframe PTFs can be accessed from the CA Gen Maintenance Grid link on that page. NOTE: For the distributed side the PTFs below which added the Call REST functionality have since been superseded by 8.6.3 Consolidation PTFs.
8) What do I have to do to my model to include Call REST functionality?
If you are creating a new model, you do not have to do anything special to add Call REST statements. If you are using an existing model, the Toolset will produce an error message indicating that the model must be converted. The procedure for correcting that error can be found in the Gen Documentation.
9) What is a URIMAP?
A URIMAP is a CICS resource that matches the URIs for Web Services requests and provides information about how requests are handled. IBM has a good definition of URIMAPs here.
10) How do I handle errors when creating a Call REST statement?
The Gen Toolset has fairly clear error messages and definitions of them can be found at Toolset Messages
The messages fall into 2 basic categories. The first set are communication errors that are generally caused by mistyping URLs or connection issues to remote services. These can generally be fixed simply by retrying the connection. The other category of errors are related to parsing the OpenAPI specification. These may be harder to fix as they could require editing the specification file to correct the problem.
11) How do I handle runtime errors using a REST API?
Currently, only Java applications can allow users to handle runtime errors. This is done by setting ERROR_HANDLING_BY_USER to Y and adding inline code to read the errors out of the global error buffer. This process is described at Error Handling in Call REST
12) How can I handle error (non 200) responses from the remote service?
For every REST call, Gen provides parameters that define the HTTP response code and can be matched to Gen attribute views. The parameter HttpResponseCode contains the code returned by the web service, and HttpResponseMsg contains a readable translation of that code. As the response code is an integer value, it can then be used in a CASE statement to provide special handling based on the response from the remote server.
Similarly, for HTTP requests that use OAuth2 authentication, the parameter AuthResponseCode contains the response code provided by the authentication service and AuthResponseMsg contains a readable translation of that code.
13) What response codes could I expect from the remote service?
The current list of HTTP Response codes can be found at https://restfulapi.net/http-status-codes
14) What are the most common errors that I might see?
The most common runtime errors are:
To fix this error, make sure that all required REST parameters are matched to Gen views and that valid data is being passed in those views
To fix this error, make sure that all Export views are marked as nullable.
This is a catch-all error for the Call REST statement. There will be additional messaging to indicate what went wrong.
The most common HTTP errors are:
The reasons for HTTP errors are dependent on how the APIs were created. The descriptions at https://restfulapi.net/http-status-codes can provide some basic information about what went wrong and how to fix it.
15) How do I change REST parameters to handle different environments?
Gen provides a number of methods to configure the Call REST statement
For additional information, please see hub article: Gen 8.6 Consuming REST APIs (Call REST) feature