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).
- 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
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 ofz/OS Connect 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.