Creating a JSON web service client application

You can write an application program to call a RESTful web service by using the linkable interface to transform JSON and then use the WEB commands to send it to the remote service provider.

Before you begin

You must be familiar with using the linkable interface to transform JSON, as described in Transforming application data and JSON using the linkable interface, and with the EXEC CICS WEB APIs, as described in Making HTTP requests through CICS as an HTTP client.

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 the linkable interface to transform your application data to JSON to use as part of the request, and transform the JSON response into application data. Some services might not support a payload for both the request and response.

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), use the linkable interface to transform your application data to JSON.
      For more information, 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, use the linkable interface to transform the JSON to application data.
      For more information, 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.