Concepts of JSON web services

Read this topic to understand the concepts behind JSON web services.

Web services

A web service is a generic term for a software function that is hosted at a network addressable location. In this general sense it can imply a Cloud based service, a Utility service or even a departmental application. The term web service can also be used in a more specific sense, such as a hosted service using SOAP which is described using a WSDL document. It is this more specific meaning that is usually implied by the term web services in CICS. However, the more general term is often used by the JSON community when describing JSON based services. JSON web services uses the term in its generic sense.

There are some important differences between SOAP and JSON:
  • The content of a SOAP message is XML data, whereas a JSON message contains JSON data. JSON and XML are different encoding mechanisms for describing structured data. JSON tends to be a more efficient encoding mechanism, so a typical JSON message will be smaller than the equivalent XML message.
  • JSON is easy to integrate in JavaScript applications, but XML isn't. This makes JSON a preferred data format with many mobile application developers.
  • SOAP provides a mechanism to add Headers to a message, and a family of specifications for qualities of service (such as security configuration, and distributed transactions). JSON does not provide this mechanism, it instead relies on the services of the underlying HTTP network protocol. This results in fewer options for securing and configuring a workload.
  • SOAP web services are described using WSDL documents. JSON web services are structured less formally; they tend to be loosely coupled and prefer documentation by example.
  • SOAP web services have an explicit error format involving SOAP Fault messages. There's no equivalent for JSON.
There are also many similarities between JSON and SOAP:
  • The CICS implementation of JSON is derived from the SOAP architecture, and shares many of the concepts and artifacts.
  • Both involve offline utility programs that assist with mapping application data to and from the external data representation. For SOAP there is DFHLS2WS and DFHWS2LS, for JSON there is DFHLS2JS and DFHJS2LS.
  • The deployment mechanism for both technologies involve a PIPELINE resource, a WEBSERVICE resource, and a URIMAP resource.

JSON schema

One disadvantage of JSON compared to SOAP is the difficulty in documenting the structure of a JSON interface. SOAP web services have the advantage of WSDL documents, together with XML schemas. A WSDL document may not be easy to understand, but there are many tools available to work with WSDL documents.

The nearest equivalent for JSON is the JSON Schema specification available at http://json-schema.org/. At the time of writing this is a draft specification which is making its way through the IETF standardization process. The CICS JSON assistant (DFHLS2JS and DFHJS2LS) supplies a partial implementation of draft 4 of this emerging specification. DFHLS2JS can be used to generate JSON schema, and DFHJS2LS can be used to process them.

You can use the JSON schema to understand the valid syntax and content model for a JSON web service that has been implemented in CICS. The JSON schema specification doesn't have the same tooling ecosystem as the XML schema specification, but a new generation of JSON tools might emerge to use this data format.

CICS implementation of JSON based web services

CICS supports three modes of JSON web service, z/OS® Connect Enterprise Edition, Request-Response and RESTful. CICS also supports a programmatic scenario in which applications can transform JSON data to and from COBOL style data formats themselves.

z/OS Connect Enterprise Edition

z/OS Connect Enterprise Edition is a separately-orderable IBM® product that runs in a standalone environment.

z/OS Connect Enterprise Edition provides RESTful API access to z/OS applications and data hosted in subsystems such as CICS, IMS, IBM MQ and Db2®. The framework provides concurrent access, through a common interface, to multiple z/OS subsystems.

z/OS Connect Enterprise Edition also provides the capability that allows CICS, IMS and z/OS applications to access any RESTful endpoint, inside or outside z/OS, through RESTful APIs with JSON formatted messages.

To learn more, see z/OS Connect Enterprise Edition product documentation.

Request-Response

The Request-Response JSON pattern is very similar to that of SOAP based web services in CICS. The web service is implemented using a PROGRAM in CICS. The PROGRAM has input and output data formats, described using language structures (such as COBOL copybooks), and CICS is responsible for transforming incoming JSON messages into application data, and linking to the application. The application returns output data back to CICS, and CICS transforms this into JSON data to return to the client.

In this scenario the JSON client must connect to CICS using 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 using the DFHLS2JS JSON Assistant. In top-down mode a new JSON web service can be developed to implement an interface described using existing JSON schemas. In top-down mode, the DFHJS2LS JSON Assistant is used to generate new language structures, and an application must be created to use them.

The Request-Response pattern may be used to build JSON Web Services that target either COMMAREA or channel-attached CICS PROGRAMs. A Request-Response JSON web service can be used only in provider mode (where CICS acts as the server).

RESTful

This scenario is different to that of SOAP web services. The concept of a RESTful JSON web service is described more completely in Concepts of RESTful JSON web services. 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 applications, so is available only in top-down mode.

A JSON schema can be processed by DFHJS2LS in RESTful mode. An application must be written to implement the service and it will have to behave differently depending on the HTTP method that was used for the incoming request.

CICS 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 applications must use a channel based program interface; COMMAREAs are not supported. A RESTful JSON web service can be used only in provider mode (where CICS acts as the server).

Programmatic mode

In this scenario an application can LINK to a CICS supplied program, DFHJSON, and ask it to transform application data into JSON data, or JSON data into application data. For example, an application might use this facility in order to generate JSON data to send to a remote JSON web service. To do this, it must contact the remote JSON web service using the CICS WEB API.

CICS has no built-in support for requester mode JSON web services, but an application can call a remote JSON web service by exploiting the programmatic mode.