Consuming REST services from CICS with EGL

Representational State Transfer (REST) Web Services are services that can be invoked using HTTP. The service provides access to a web resource that is specified in a URI. The service’s operations correspond to HTTP operations, the following four are supported in EGL:

• GET – for retrieving resources
• POST – for creating resources
• PUT – for creating or updating resources
• DELETE – for deleting resources

EGL provides a common framework for applications to consume REST Web Services. This framework has four components:

1. An EGL Interface part that describes the operations made available by the REST service and the parameters that are passed.
2. An EGL Service variable that is based on this interface. This variable is used by the EGL application to invoke the REST service.
3. An EGL Deployment descriptor that binds the EGL Interface to a REST service.
4. An EGL ServiceLib library that provides a set of functions for customizing the REST invocation and processing the response.

In EGL, a REST service’s URI is split into two components:

1. A base URI, or the leading part of the URI, which is usually the address of the REST service.
2. A URI template, or the trailing part of the URI, which is usually the name of the service and the parameters of the service.

At runtime, the base URI and the URI template are concatenated to form the complete URI for invocation. So, it is also possible to have the full URI in either the base URI or the URI template.

For example, if a REST Service has a URI as follows: 

http://www.example.com/myservice?q={myquery}&numReturnRows={rowCount}, the base URI is http://ww.example.com and the URI template is /myservice?q={myquery}&numReturnRows={rowCount}.

Note : myquery and rowCount are parameters whose values are substituted at runtime.

EGL Interface for consuming REST Services

Functions in an EGL Interface are mapped to a REST Operation using the @Rest annotation. There are four types of @Rest annotations that are available, which correspond to the four main REST Operations:

• @GetRest
• @PutRest
• @PostRest
• @DeleteRest

Figure-1 shows an example of an EGL Interface that can be used to invoke a REST Service. In this example, the Service is called myservice and it operates on a Web Resource described by the record myUserData. The value of the parameters myquery, myUser and rowCount are used to create the full URI needed to invoke the REST Service. Any number of parameters can be used in the uriTemplate, but only one parameter (in this case myUserData) can be used as the resource representation that is sent to and received from the REST Service. This parameter is placed in the body of the HTTP request and response.                    

Figure-1: An example interface for REST

Each of the @Rest annotations has the following three properties:

1. uriTemplate

    This property allows Users to parameterize the URI. Each parameter in the URI corresponds to a parameter defined in the function. At runtime, the values of the parameters are substituted into the URI, which is then appended to the base URI to create the full URI needed to invoke the Service.

2. requestFormat

    This property specifies how the request data is to be formatted when sent to the REST Service. The following are the four formats available in EGL:

• NONE – the request data is sent as a string
• XML –  the request data is an EGL record which is converted at runtime to XML
• JSON – the request data is an EGL record which is converted at runtime to JSON
• FORMDATA – the request data is an EGL record whose fields are all strings or assignable to strings. At runtime, the EGL record is converted to a string of name-value pairs separated by ‘&’.

3. responseFormat

    This property specifies the format that the REST Service uses to send back data. The following are the three formats that EGL can understand:

• NONE – the response data is a raw string that is sent to the EGL client as-is
• XML – the response data is an XML-formatted string that is to be converted to an EGL record
• JSON – the response data is a JSON-formatted string that is to be converted to an EGL record

Accessing REST Services In EGL

To access a REST Service in an EGL Program, a service variable that is based on an EGL REST Interface must be defined, which can be used to invoke the REST functions.

For example, using the ISampleService interface shown in Figure-2, a REST Service can be invoked using the following code:

Figure-2: Invoking REST Services From EGL

Note : The interface is annotated with details on how to bind the service variable to a REST Service.

@BindService

The Service Binding is declared in an EGL Deployment Descriptor. The binding is accessed using a key, which in this case is “ISampleService”. If the bindingKey is not specified, the key is the name of the EGL Interface (in this case “ISampleService”).

@RestBinding

The Service Binding is declared within the annotation.

baseUri

The location of the REST Service includes the service address and an optional port number. This baseUri is concatenated with the uriTemplate defined in the EGL Interface to create the full URI for calling the service.

Exception handling with REST calls

If an error occurs while invoking the REST Service, the following two service-specific exceptions may be thrown.

ServiceBindingException

This exception is thrown when the service binding referred by the bindingKey option does not exist in the EGL Deployment Descriptor.

ServiceInvocationException

If the REST Service returns an error (for example, HTTP status 500 Internal Server Error), an EGL ServiceInvocationException is thrown. This exception record contains three detail fields which contains more information on why the invocation failed.

Detail1

This field contains the full URI used to invoke the service.

Detail2

This field contains the HTTP status code and message (for example, 500 Internal Server Error).

Detail3

This field contains the response message from the REST Service.

Specifying Service Binding in the Deployment Descriptor

To resolve the REST Service Binding at runtime, specify the Service Binding in an EGL Deployment Descriptor.

Complete the following steps to configure the Service Bindings in the Deployment Descriptor.

Step 1:  Open the EGL Deployment Descriptor for the project. Go to the Service bindings tab and click Open. Select REST service binding and click Next.

Step 2: Click Browse to find the required REST Interface. Set the Base URL field to the location of the REST Service that is to be invoked. Click Finish.

Figure-3: Final Service Binding Ready For Deployment

Deploying EGL REST Clients for CICS

The EGL REST client program and the EGL Deployment Descriptor (if used) must be generated using a Build Descriptor with target system CICS. The client application is generated as a COBOL application, the Deployment Descriptor is generated as a COBOL based bind program containing all the Service Bindings defined in the Deployment Descriptor. This bind program is called by the EGL REST client program to resolve the REST binding at runtime.

EGL Library functions for CICS REST Services

The EGL Service Library serviceLib contains several functions for customizing the REST invocation and processing the response. The following functions are available for CICS:

bindService (bindingKey String) :

Returns a Service Binding that matches the bindingKey in the EGL deployment descriptor file. This function can be used to change the service binding at runtime.

setHttpBasicAuthentication (service variable, username string, password string) :

Sets the username and password for invoking the specified service. For CICS, the service variable must be specified and defined with the @BindService annotation.