CICS REST web services are a feature of Enterprise Server for .NET for invoking CICS transaction programs from outside the CICS region, using HTTP. They are described in more detail in About CICS REST Web Services.
Since REST web services use HTTP, the interface is composed of HTTP methods, URLs, headers, message bodies, and response codes.
REST web services use the method of the HTTP request message to indicate to the server what sort of action to perform. Enterprise Server for .NET CICS REST services currently support the GET and POST methods. The only difference between these two methods is how the client program's application data, if any, is passed to the CICS region. The method does not affect how the application transaction program receives the data — in either case it is passed as a CICS commarea.
GET /rest/default/TRAN?commarea=Test%20data HTTP/1.1
A request using the POST method passes the application data in the message body, after the HTTP header block. In this case it is encoded as a JSON (Javascript Object Notation) object, containing the commarea data as either a string or an array of bytes, as described in more detail below.
If the client application does not need to pass any data to the service, the GET method should be used.
A client invokes a REST service by specifying a URL (Universal Resource Locator), which specifies the protocol or scheme ("http"), the host and port to connect to, a resource path, and optionally a query string (as described under "Methods" above). The path and query parts of the URL become the Request-URI of the request message sent to the server. (URI, for Universal Request Identifier, is a technical term for a class of strings that includes URLs.)
Enterprise Server for .NET CICS uses the path part of the Request-URI to determine which REST service configuration applies to the request, and which CICS transaction program to invoke. The last element of the path is the name of the transaction program: it should match a CICS PCT definition in the region (either configured at region startup, or installed dynamically while the region is running). The other path elements are matched against REST service configurations specified in the region startup file, which can contain wildcards; see Configuring REST Web Services. A REST service configuration can specify various optional parameters that affect how the service works. If there is no matching configuration, the request is rejected.
In the example given above in the "Methods" section, the transaction program that will be invoked is named TRAN, and the configuration that will be used is the one that best matches /rest/default. The "best match" is determined by the smallest number of substitutions that have to be made to replace wildcard characters in the configuration path with characters from the Request-URI. For example, this path would match /rest/d* more closely than it would match /rest/*.
HTTP messages include a series of headers describing the message, and the REST web services feature makes use of some of them.
Some headers are required by the HTTP protocol itself, as described in the IETF standard RFC 2616 (available from rfc-editor.org and various other sources). These will generally be applied automatically by a client framework or library for the request, and handled automatically when processing the response: the application usually does not have to deal with them. There are a few headers which are significant for CICS REST web services:
As described above, a REST web service request that uses the POST method to send application data in a request will put the data in the HTTP message body. Similarly, if there is any application data in the response to a REST web service (that is, if the transaction program puts data in its commarea before returning to CICS), that will be sent back to the client as the message body of the HTTP response.
In either case, the message body is encoded using JSON, the Javascript Object Notation, a standard plain-text encoding that is specified by the IETF standard RFC 4627. The JSON object represents the commarea in one of two forms, as an object with one member. The member can either be a string named commarea, or an array of bytes named binaryCommarea. (If both members are present in a request, binaryCommarea takes precedence and commarea is ignored.) The binaryCommarea version can be used for any commarea and is most useful when the application's commarea is defined in a way that is not convenient to represent as a string, such as a COBOL group item or an object that is serialized in binary form. commarea is a useful alternative when the commarea only contains text, since it's easy to generate and to read in traces.
An example of a string commarea:
{ "commarea": "text commarea data" }
An example of a binary commarea:
{ "binaryCommarea": [98, 105, 110, 97, 114, 121] }
In a Microsoft.NET program, you can use the JsonSerializer class to convert to and from JSON. The RestClient convenience class provided with Enterprise Server for .NET will automatically perform the conversion for client programs.
Enterprise Server for .NET CICS REST web services use standard HTTP response codes, which are described in full in RFC 2616. Response codes, which appear on the first line of the HTTP response message, indicate the success or failure of the request, or other information about its status. A code in the range 200-299 indicates success; codes 400 and above are errors. The server currently uses the following codes:
Usually server errors are handled by the client API and signalled to the client program by an error return code or an exception, but it is often useful to examine the response code and the body of the message (which will be a plain-text document with additional information about the error) to determine why the request failed.