Creating a RESTful web service provider application

The CICS® implementation of RESTful JSON web services is similar to that of SOAP web services. Most of the concepts and architecture are shared, but CICS requires the use of a JSON schema.

1. Generate the application interface.
   Input:

   • The JSON schema that defines the data model for the RESTful web service.

   Output:

   • The language structures (for example, COBOL copy book) that map the JSON schema.
   • A WSBind file.
   Run the DFHJS2LS utility and specify the appropriate input parameters. These parameters include:

   • The location of the JSON schema.
   • The list of supported methods (GET, PUT, POST, and DELETE are enabled by default).
   • The URI at which the service is deployed.
   • The name of the application PROGRAM that implements the service.
   • Any required data-mapping parameters.
2. Create an application that uses this interface.
   Input:

   • The language structures from step 1.
   • An awareness of which RESTful operations will be implemented
   Output:

   • A program suitable for deployment to CICS
   Write a program that does the following:

   Note: If you supply the name of your own container on the CONTID parameter to DFHJS2LS, you must use this container instead of DFHWS-DATA whenever it is mentioned in the following steps.

   1. Examine the URI to understand the identity of the resource. CICS provides several containers to help you identify interesting components of the URI. The containers are described in Table 1. The examples show the contents of each container for the URI:

      http://www.example.org:10000/JSONServices/CustomerDetails/13388?action=query

      If the URIMAP that matched has PATH of /JSONServices/CustomerDetails/*

      Table 1. . DFHWS-URI containers

      Container	Contents	Example
      DFHWS-URI	The complete URI	http://www.example.org:10000/JSONServices/CustomerDetails/13388?action=query
      DFHWS-URIMAPPATH	The portion of URI path that matched the URIMAP	/JSONServices/CustomerDetails/*
      DFHWS-URI-RESID	The URI path with the portion matched by the URIMAP removed (the resource identifier)	13388
      DFHWS-URI-QUERY	The query string	action=query

   2. Validate the URI. If there is a problem, report the problem to CICS and terminate.
   3. Query the DFHHTTPMETHOD container to determine which method is being driven. For more information, see DFHHTTPMETHOD Control Container.
   4. For a POST (create) method (if needed):
      • Read the input data from the DFHWS-DATA container.
      • Interpret the data by using the language structure(s) generated in step 1.
      • Validate the data. If there is a problem, report the problem to CICS and terminate.
      • Perform whatever application-specific processing is required to create the 'resource'.
      • Optionally, write to the DFHRESPONSE container to notify the client of the identifier of the new resource. The contents of this container are not transformed by CICS, but sent directly in the HTTP response. The DFHWS-DATA container is ignored.
   5. If a GET (inquire) or HEAD (inquire) method is needed, write the data that represents the 'resource' to the DFHWS-DATA container.
   6. If a PUT (set) method is needed:
      • Read the input data from the DFHWS-DATA container.
      • Interpret the data by using the language structure(s) generated in step 1.
      • Validate the data. If there is a problem, report the problem to CICS and terminate.
      • Perform whatever application-specific processing is required to update the 'resource'.
   7. If a DELETE method is needed, perform whatever application-specific processing is required to delete the 'resource'.
   Note: The RESTful data model that is implemented by CICS does not send a response body for the PUT, POST, or DELETE methods by default. RESTful applications typically use the HTTP status code to indicate success or failure. If the application completes normally, CICS sends an HTTP response of 200 (OK). For more information about sending error responses, see Application error reporting. If you want to send a response body for a PUT, POST or DELETE method, you must write the DFHRESPONSE container. If present, CICS sends the contents of this container in the HTTP body without further processing. CICS ignores the DFHWS-DATA container in the response processing for these methods.
3. Deploy the artifacts
   Input:

   • The WSBind file from step 1.
   • The CICS Program from step 2.
   • A CICS provider mode pipeline resource that is configured for JSON.
   Output:

   • A deployed RESTful JSON web service.

   Deploy the program to CICS in the normal way.

   Either:

   • Deploy the WSBind file to the Pipeline's 'pickup' directory; then issue a PIPELINE SCAN command to create the WEBSERVICE and URIMAP resources.
   • Manually define and install a WEBSERVICE resource and associated URIMAP resource. The URIMAP must associate the URI with both the PIPELINE and the WEBSERVICE.
4. Test the service
   Input:

   • The JSON schema.
   • The URI of the RESTful web service.
   • The deployed service from step 3.
   • A JSON test client of your choice.
   Output:

   • A successfully handled request.

   Use the test client of your choice to send a JSON request to CICS.

   If you receive an unexpected response, attempt problem determination. For more information, see Troubleshooting problems with JSON requests.