Concepts of RESTful JSON web services

The concepts behind RESTful web services and how they differ from Request-Response services.

RESTful web services

REpresentational State Transfer, or REST, is a design pattern for interacting with resources stored in a server. Each resource has an identity, a data type, and supports a set of actions. The RESTful design pattern is normally used in combination with HTTP. In this context, the resource's identity is its URI; the data type is its Media Type; and the actions are made up of the standard HTTP methods (GET, PUT, POST, and DELETE).

This style of service differs from Request-Response style web services as follows:
  • Request-Response services interact with a program, whereas RESTful services typically interact with data (referred to as resources).
  • Request-Response services involve application defined operations, but RESTful services avoid application-specific concepts and rely instead on using just the HTTP methods to specify the operation.
  • Request-Response services have different data formats for each message, but RESTful services typically share a data format across different HTTP methods.

The four major HTTP methods define the four operations that are commonly implemented by RESTful Services. The HTTP POST method is used for creating a resource; GET is used to query it; PUT is used to change it; and DELETE is used to remove it. The most common RESTful architecture involves a shared data model that is used across these four operations. This data model defines the input to the POST method (create), the output for the GET method (inquire) and the input to the PUT method (replace). This simple design pattern is popular within the RESTful community, but it is not the only RESTful design pattern. Some RESTful APIs are designed in other ways.

A fifth HTTP method, called HEAD, is sometimes supported by RESTful web services. This method is equivalent to GET, except that it returns only HTTP headers, and no body data. It can be used to test the existence of a resource without returning the resource data itself. Not all RESTful APIs support the use of the HEAD method.

Traditional CICS® applications are unlikely to match the RESTful architectural pattern. Typical CICS applications implement multiple operations, each of which have data models for input and output formats. These existing operations are unlikely to map directly to the four HTTP methods. For this reason, the RESTful architectural pattern is primarily aimed at new applications in CICS. To expose existing CICS applications as RESTful web services, you might need to wrap them with a new interface that conforms to the RESTful principles.

The URI

The identity of a RESTful service is indicated by its URI. A URI can be made up of several components, including the host name, port number, the path, and an optional query string. The domain name and port number together target a configured HTTP or HTTPS protocol handler in CICS TG. The URI path is a qualifier, and might be sufficient to uniquely identify the service. However, many RESTful web services use an extra query string to identify the precise resource. Consider the following examples:
  • http://www.example.org:10000/JSONServices/AccountService
  • https://www.example.org:10000/JSONServices?Service=Account

In the first example, the URI path is JSONServices/AccountService. In the second example, the path is JSONServices and there is an extra query string of Service=Account. Both styles of URI are considered to be acceptable for a JSON web service implementation.

The URI used to start the web service is defined in the Uri parameter of a CICS TG web service definition or the WSBind file. This URI can contain a query string.