Creating a RESTful JSON web service

How to create a RESTful JSON web service.

Procedure

Create a JSON Schema to describe the format of the RESTful JSON data.
Run the JSON web services assistant to create a WSBind file and high-level language structure.
Write a CICS® program using the generated high-level language structure that implements the business logic for the JSON web service.
Configure CICS Transaction Gateway with a HTTP or HTTPS protocol handler and a JSON web service using the generated WSBind file. For more information, see Configuring JSON web services.
Start CICS Transaction Gateway and test that you can invoke the JSON web service.

The JSON assistant

Run the CICS TG JSON web services assistant by customizing CTGJS2R.txt sample parameter file, or create your own parameter file using MAPPING-MODE=JS2LS with JSON-SCHEMA-RESTFUL and running ctgassist <parameter file>. The assistant generates a WSBind file and high-level language structure from the JSON Schemas provided. Consider these options when you are creating a new application for web services:

Which HTTP methods will the web service support? By default, the GET, POST, PUT, and DELETE methods are all enabled, but you might not want to support all of these methods, or you might want to also support the HEAD method. Specify which methods are enabled with the HTTP-METHODS parameter.
Which language do you want to generate? The assistant can generate COBOL, C/C++, or PL/I language data structures. Specify the language with the LANG parameter.

For more information, see Creating a RESTful WSBind file.

Writing the CICS program

For all HTTP methods except DELETE, data is passed to and returned from the CICS program in a single BIT container, which is named DFHWS-DATA by default. To use a container with a different name, specify the CONTID parameter when you run the assistant. The data in the container conforms to the language structure generated by the assistant.

In addition to the data container, the following CHAR containers are passed to the CICS program:

Table 1. CHAR containers passed to the CICS program
Container name	Description
`DFHHTTPMETHOD`	The HTTP method that is used to call the web service, such as GET, POST, PUT, DELETE, or HEAD. The value is padded with spaces to a length of 8 characters.
`DFHWS-URIMAPPATH`	The URI property of the CICS TG web service definition that was matched.
`DFHWS-URI`	The path of the URI used to call the web service.
`DFHWS-URI-QUERY`	The query string of the URI used to call the web service.
`DFHWS-URI-RESID`	The resource ID of the URI used to call the web service. The resource ID is the portion of the URI that was matched by the wildcard character.

The CICS program can use the following CHAR containers to report errors to the client application by setting the HTTP status code, and to return non-JSON responses:

Table 2. CHAR containers received from the CICS program
Container name	Description
`DFHHTTPSTATUS`	Specifies the HTTP status code to return to the web service client. The content of the container must be the same as the initial status line of an HTTP response message, which has the following structure: `HTTP/1.1 nnn tttttttt` where `nnn` specifies the three-digit decimal HTTP status code and `tttttttt` specifies the human-readable status text that is associated with the status code.
`DFHRESPONSE`	Specifies the content of the HTTP response that is returned to the web service client.
`DFHMEDIATYPE`	Specifies the content type of the data in the `DFHRESPONSE` container. The content of the container must consist of a type and subtype that are separated by a slash character. For example: `text/plain image/svg+xml`

When the GET or HEAD method is used to call the web service, no data is passed to the CICS program. The program must update the language structure with data associated with the resource specified in the DFHWS-URI-RESID container, then write the language structure into the data container. To report an error, the program must use the DFHHTTPSTATUS container to set the HTTP status code.

When the POST or PUT methods are used to call the web service, data is passed to the CICS program in the data container. The program must read the language structure from the data container and use the contents to create a new resource (POST) or update an existing resource (PUT). To return a response to the client, such as the identifier or URI of the new resource, the program must use the DFHRESPONSE and DFHMEDIATYPE containers. To report an error, the program must use the DFHHTTPSTATUS container to set the HTTP status code. When the DELETE method is used to call the web service, the data container is not used. The program deletes the resource that is specified in the DFHWS-URI-RESID container. To report an error, the program uses the DFHHTTPSTATUS container to set the HTTP status code.

The data is aligned differently depending on the value of TARGET-CICS-PLATFORM, for more information, see Creating a Request-Response WSBind file from JSON Schemas.