Creating a JSON web service client application

You can write an application program to call a RESTful web service by using either the TRANSFORM DATATOJSON and TRANSFORM JSONTODATA API commands or the linkable interface, DFHJSON, to transform JSON and then using the WEB commands to send it to the remote service provider.

Before you begin

You must be familiar with the EXEC CICS WEB APIs, as described in Making HTTP requests through CICS as an HTTP client.

If you intend to write applications that use JSON for purposes other than a web services client, see Mapping and transforming application data and JSON.

About this task

As part of a CICS® application you might want to call a RESTful web service hosted on another system. To do this, you must first describe the data to be exchanged with the remote service. You can then write an application program that uses the EXEC CICS WEB API to communicate with the remote service with the HTTP protocol to send request data to the service and receive response data. You can use either the TRANSFORM DATATOJSON API command or the linkable interface, DFHJSON, to transform your application data to JSON to use as part of the request, and use either TRANSFORM JSONTODATA or DFHJSON to transform the JSON response into application data. Some services might not support a payload for both the request and response.

The linkable interface DFHJSON is an older technology, superseded by the EXEC CICS TRANSFORM API commands. Although both can be used to convert JSON data to and from copybook-defined application data, you are advised to use the EXEC CICS TRANSFORM API commands.

Procedure

  1. Define the interface to the remote service.
    1. If the remote service exists, check to see whether a JSON schema is available that describes the request and response payloads. If not, you must create one. Then, use the JSON assistant to generate a mapping to a language structure. For more information, see Generating mappings from a JSON schema.
    2. If the remote service does not yet exist and you want to base its interface on your application's data structure, use the JSON assistant to generate a JSON schema. Then, pass the JSON schema to the remote service application developer. For more information, see Generating mappings from language structure.
  2. Define a BUNDLE resource for the bundle that is generated by the JSON assistant and install the bundle in CICS.
  3. Define a URIMAP resource for the remote service endpoint and install it.
    For more information, see URIMAP resources.
  4. Create or update an application program to call the remote service as follows:
    1. If the remote service requires a JSON payload for the request (for example when the HTTP method is POST or PUT), transform your application data to JSON.
      To use TRANSFORM DATATOJSON to process data conversion in your application, see Transforming application data to JSON by using the TRANSFORM DATATOJSON API command.

      To use the linkable interface, DFHJSON, to let CICS or a JVM server to process data conversion, see Transforming application data to JSON by linking to DFHJSON.

    2. Open a connection to the server where the remote service is hosted, by using the EXEC CICS WEB OPEN command.
      For more information, see WEB OPEN.
    3. Depending on the requirements of the service, you might want to code the EXEC CICS WEB WRITE HTTPHEADER command to specify the Content-Type header application/JSON to indicate that JSON is being supplied.
      For more information, see WEB WRITE HTTPHEADER.
    4. Code an EXEC CICS WEB CONVERSE command to send the request to the remote service and receive the response. Specify the query string or request body (from the DFHJSON-JSON container) if required. If you expect a response from the service, specify the DFHJSON-JSON container to receive the response JSON.
      For more information, see WEB CONVERSE.
    5. If you do not expect to make further requests, code an EXEC CICS WEB CLOSE command to close the connection.
      For more information, see WEB CLOSE.
    6. Check the HTTP response code that is returned by the EXEC CICS WEB CONVERSE command and take appropriate action if an error occurred.
      For example, try the request again or return an error to the user.
    7. If a response body was expected from the remote service, transform the JSON response to application data.
      To use the TRANSFORM JSONTODATA API command, see Transforming JSON to application data by using the TRANSFORM JSONTODATA API command.

      To use the linkable interface, DFHJSON, see Transforming application data to JSON by linking to DFHJSON.

Results

You have created an application that can call a RESTful web service with a JSON payload.