JSON web services

CICS® TG can create web services that use JavaScript Object Notation (JSON) for HTTP request and response payloads.

CICS TG converts the JSON data into a channel or COMMAREA payload, which is then passed to a CICS program. CICS TG then converts the data returned from CICS back to JSON.
Diagram showing a web service client targeting a COMMAREA or channel attached CICS program.

CICS TG supports two types of JSON web service, Request-Response and RESTful:

Request-Response

A Request-Response web service accepts a JSON object as input and produces another JSON object for output. The web service is implemented by a program in CICS, and CICS TG is responsible for transforming the incoming JSON object into application data and calling the program in CICS. The application returns output data back to CICS TG, and CICS TG transforms the output data into JSON data to return to the client.

In this scenario, the web service client must call the web service with the HTTP POST method.

A Request-Response mode JSON web service can be developed in either bottom-up mode or top-down mode.

In bottom-up mode, an existing CICS program is exposed as a JSON web service. The JSON web services assistant is used to generate new JSON Schemas that describe the input and output JSON data of the web service based on existing high-level language structures.

In top-down mode a new JSON web service can be developed to implement an interface that is described by existing JSON Schemas. The JSON web services assistant is used to generate new high-level language structures, that describe the CICS program payload based on the existing JSON Schemas.

The Request-Response pattern can be used to build JSON web services that target either COMMAREA or channel based CICS programs.

RESTful

A RESTful JSON web service implements the architectural principles of the REpresentational State Transfer (REST) design pattern. This design pattern is unlikely to be relevant for existing CICS programs, so is available only in top-down mode.

A JSON web services assistant is used to generate new high-level language structures that describe the CICS program payload based on the existing JSON Schema. A CICS program must be written to implement the service and it needs to behave differently depending on the HTTP method and URI that was used for the incoming request.

CICS TG implements a pure style of RESTful application, where the data format for POST (create) GET (inquire) and PUT (replace) are the same. RESTful JSON web service programs must use a channel-based program interface. Using a COMMAREA is not supported. This means that RESTful JSON web services can only be implemented when CICS TG is connected to CICS using the IPIC protocol.

For more information, see Concepts of RESTful JSON web services.

Creating a JSON web service

You can create a JSON web service from high-level language structures (bottom-up) or from JSON Schemas (top-down). The JSON web services assistant helps you create a JSON web service by generating a WSBind file, and JSON schemas or high-level language structures. There are two versions of the CICS TG JSON web services assistant:
  • a JCL based assistant for running on IBM® z/OS®
  • ctgassist for running on distributed systems
Both versions of the assistant generate the same output. Choose the version of the assistant that is supported for the platform you want to run it on. The distributed version of the assistant is located in the CICS TG SDK directory cicstgsdk/webservices/assistant.
Diagram showing bottom-up mode where an existing CICS program can be run as a JSON web service by the CTGLS2JS JSON assistant.
Diagram showing top-down mode where an interface is developed from a JSON Schema.

WSBind files

A web service binding (WSBind) file describes which CICS program is called and how the data is transformed between JSON data format and CICS program payload when a JSON web service is started.

JSON Schemas

JSON Schemas are used by JSON web services to describe the JSON data format for HTTP request and response payloads. For more information on the JSON Schema specification, see http://json-schema.org/. At the time of writing this is a draft specification which is making its way through the Internet Engineering Task Force (IETF) standardization process. The JSON web services assistant supplies a partial implementation of draft 4 of this emerging specification.