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 , 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
z/OS Connect enables CICS programs to be called with a JavaScript Object Notation (JSON) interface. z/OS Connect for CICS was first introduced as an alternative to the JSON capabilities of the java pipelines that were provided in the CICS TS Feature Pack for Mobile Extensions and integrated into CICS TS Version 5.2. Since then, z/OS Connect has grown into a separate product, called z/OS Connect Enterprise Edition, with additional capabilities.

z/OS Connect is IBM®'s premiere technology for implementing JSON Services and APIs in CICS. It is available in three versions, and supports several deployment options. z/OS Connect for CICS is the entry level edition and a low-cost option, but lacks the enhancements of the other versions. z/OS Connect EE version 2.0 and 3.0 offer a further range of integration options.

z/OS Connect EE is a separately-orderable IBM product. It builds on the capabilities of z/OS Connect for CICS, which included support for JSON services. z/OS Connect EE enables API developers to construct JSON APIs from JSON services. The APIs are constructed and packaged with the Eclipse-based API Editor that is provided with z/OS Connect EE, then deployed to the z/OS Connect runtime. The API package includes Swagger 2.0 definitions to make it easier for developers to incorporate the APIs into their applications. Key z/OS Connect capabilities, such as authorization security checking for service invocation, creation of System Management Facility (SMF) records, and logging of RESTful service requests also apply to the APIs.

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.