Concepts of RESTful JSON web services

Read this topic to understand the concepts behind RESTful web 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, the language of the internet. 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:
  • Request-Response services start interaction with an Application, 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.
  • Request-Response services have different data formats for each message, but RESTful service 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 destroy 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's not the only RESTful design pattern. The HTTP status code is used to indicate success or failure of the operation. 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's sometimes used to test the Existence of a resource. Not all RESTful APIs support 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 will 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 Services you may 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 TCPIPSERVICE resource in CICS. For more information, see TCPIPSERVICE resources . The URI path is a qualifier, and might be sufficient to uniquely identify the service. However, many RESTful web services use an additional 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 additional query string of Service=Account. Both styles of URI are considered to be acceptable for JSON. This is an important difference compared to SOAP. Under SOAP the first style of URI is preferred.

CICS JSON services can be converted into RESTful services using z/OS® Connect Enterprise Edition. A Graphical User Interface is used to map URI fragments and HTTP headers into fields of an existing copybook, and different programs can potentially act as the target for each HTTP method. The ability to construct RESTful services from existing application assets is one of the main advantages of z/OS Connect Enterprise Edition over the other JSON technologies in CICS.

CICS also has an older technology for implementing a limited form of RESTful service. A URIMAP resource can be used to identify the appropriate WEBSERVICE and PIPELINE to use when processing an inbound message. The URIMAP can map a URI to a specific PIPELINE or WEBSERVICE, potentially including the query string of the URI in that mapping

CICS uses a URIMAP resource to identify the appropriate WEBSERVICE and PIPELINE to use when processing an inbound message. The URIMAP supports use of a query string as part of the path attribute. Therefore the URIMAP is suitable for use with both types of URI.