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.
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
-
Define the interface to the remote service.
-
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.
-
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.
-
Define a BUNDLE resource for the bundle that is generated by the JSON assistant and install the
bundle in CICS.
-
Define a URIMAP resource for the remote service endpoint and install it.
-
Create or update an application program to call the remote
service as follows:
-
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.
-
Open a connection to the server where the remote service is hosted, by using the EXEC
CICS WEB OPEN command.
-
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.
-
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.
-
If you do not expect to make further requests, code an EXEC CICS WEB CLOSE
command to close the connection.
-
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.
-
If a response body was expected from the remote service, transform the JSON response to
application data.
Results
You have created an application that can call a RESTful web
service with a JSON payload.