JSON web services
CICS TG supports two types of JSON web service, Request-Response and RESTful:
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.
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
- a JCL based assistant for running on IBM® z/OS®
- ctgassist for running on distributed systems
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 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.