Gen 8.6 Consuming REST APIs: FAQ

Products

Gen Gen - Host Encyclopedia Gen - Run Time Distributed Gen - Workstation Toolset

Issue/Introduction

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.

Environment

Gen 8.6
Java applications
COBOL application executing on CICS

Resolution

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?

Publishing a RESTful Web Service – A Web Service is published when it becomes available on the internet or intranet.
Consuming a RESTful Web Service – To consume a Web Service, a program sends a request to the remote service and then processes the response to that request.

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:

- Available endpoints and the operations for each endpoint
- The input and output parameters for the endpoint and operation
- Authentication for the service
- Additional information about the API

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.

- For the Mainframe, the required PTFs are:
  - LU03408 – Host Encyclopedia support for consuming RESTful APIs
  - LU03409 – CICS Common Module support for consuming RESTful APIs
  - LU03410 – CICS Runtime support for consuming RESTful APIs
  - LU05281 – CICS Runtime security schemes support for consuming RESTful APIs

- For Client Server Encyclopedias, the PTFs are:
  - CSI86210 – HP UX CSE support for consuming RESTful APIs
  - CSN86212 – Windows CSE support for consuming RESTful APIs
  - CSR86210 – AIX CSE support for consuming RESTful APIs

OR

- - CSI86300 - Gen 8.6.3 Consolidation PTF (HP/UX CSE)
  - WKS86300 - Gen 8.6.3 Consolidation PTF (Windows CSE)
  - CSR86300 - Gen 8.6.3 Consolidation PTF (AIX CSE)

- To add Call REST statements to your models, the PTFs are:
  - TSN86221 – Toolset support for consuming RESTful APIs
  - GEN86212 – Generator changes to support RESTful APIs
  - TSN86225 – Toolset security schemes support for consuming RESTful APIs

OR

- - WKS86300 - Gen 8.6.3 Consolidation PTF

- To use Call REST in Java applications, the PTFs are:
  - BTN86209 – Build Tool changes to incorporate the runtime jars in the application
  - RTJ86208 – Java runtime support for consuming RESTful APIs
  - RTJ86210 – Java runtime security schemes support for consuming RESTful APIs

OR

- - WKS86300 - Gen 8.6.3 Consolidation PTF

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:

- TIRM304E – Invalid (NULL) value trying to perform external call

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

- TIRM305E – Could not locate value trying to perform external call

To fix this error, make sure that all Export views are marked as nullable.

- TIRM322E – Error occurred while performing external call

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:

- 400 – Bad Request
- 401 – Unauthorized
- 403 – Forbidden
- 404 – Not Found
- 500 – Internal Server Error

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

- Default – If none of the configuration parameters have been defined, the code will use the URL from the OpenAPI specification and a set of default values
- Global – The callrest.properties file can define parameters that apply to all REST calls. These apply to any parameter except for the URL and override the default values
- Service – If a service is defined in the callrest.properties file, then parameters for that service override the global value and the defaults.
- Runtime – You can match configuration parameters to Gen attribute views. If these values are matched, the runtime will use those values for the REST calls, overriding any prior parameter definitions.
- User Exit – The URL for the RESTful Web Service can be set using the modifyURL method in the WebServiceMethodCallExit user exit. This method will override any prior URL definition.

Additional Information

For additional information, please see hub article: Gen 8.6 Consuming REST APIs (Call REST) feature