Creating CICS REST Service provider in Business Developer

Content

Introduction

The CICS implementation of RESTful web services is similar to that of SOAP web Services, but CICS requires the use of a JSON schema. Each URL sent from the client is called a request, while the data sent back to the user from the server is called a response.

The scenarios described in this paper explain how the communication on request & response between the Server & Client for CICS rest services.
Prerequisites

• IBM Rational Business Developer (RBD). 
• Knowledge of developing code using EGL. 
• Knowledge of generating the COBOL programs from EGL.

Pipeline Configuration 

The pipeline configuration file is stored in the z/OS® UNIX System Services file system, and its name is specified in the CONFIGFILE attribute of a PIPELINE resource definition. When CICS processes a web service request, it uses a pipeline of one or more message handlers to handle the request.

Location Unix Shell Path: /u/rbdtest/services (this should match on the destdirectory in the builddescriptor)

Configuration file: basicRESTprovider.xml

• A PIPELINE resource definition is required for every web service. It provides information about the message handler programs acting on a service request and the response.

• A TCPIPSERVICE definition is required in a service provider that uses HTTP transport. It contains information about the port on which inbound requests are received.

• A WEBSERVICE resource definition is required only when the mapping between application data structure and messages has been generated using the CICS web services assistant. It defines aspects of the runtime environment for a CICS application program deployed in a web services setting.

• A URIMAP definition is also required if user use HTTP basic authentication because the URIMAP resource definition specifies that the service requester user ID information is passed in an HTTP authorization header to the service provider.

EGL Program

• To define an EGL Interface part in a file that is made available to the requester of that service. The Interface part can be in the same EGL package or imported from a separate package.

• Here is the sample service to implement the above specified Interface.

• During the Deployment Descriptor generation, WSBIND file will get created by using CICS JSON assistant procedure DFHJS2LS. The generated WSBIND file is moved into the UNIX directory in the Mainframe, defined in the Build Descriptor. 

Mainframe UNIX Shell path directory: /u/urbdtest/services/RESTprovider

• Declaring a variable to access a REST service (RUI As client in the example)

Response Message to Client:

• SetCICSRestResponse function sets the HTTP response headers from a CICS REST service. This function is available in an EGL-generated CICS REST service.

Example: (POSTMAN)

Restrictions:

We have some restrictions on this design as below:

• For all methods, the path & query parameters should be in order - path parameters should be first, and query parameters (?) should be next. At the same time, variables having in the function should be in the same order while handing on the path and query parameter.
• The single record must be used when multiple methods are present in the same EGL service.
• The BOOLEAN datatype doesn’t support in Path & Query parameter. It supports the REQUEST body.
• EGL record of Array supports only in GET Method.
• Currently, RBD supports the data types like Integer, Decimal, String, and Boolean for the REST Methods GET, POST, PUT, and DELETE.
• For FLOAT fields, we should define the DECIMAL as a datatype in the EGL language.
• The user should create a CPIH TWASIZE as 01024 with a different group id apart from DFHPIPE, which is CICS default.