Design considerations for RESTful web service provider applications

A common design for RESTful APIs is to support the retrieval of collections of resources. For example, a Service might exist that returns a set of objects as follows:

GET /Services/CustomerDetails?Surname=Cooper

This request is expected to return information on all CustomerDetails objects where the Surname is "Cooper". Individual CustomerDetails objects may be returned using a more specific URI such as:

GET /Services/CustomerDetails/Customer27

In this example Customer27 is the primary key for a specific customer. The output from this second query will be an instance of the CustomerDetails object. The output from the first query is less clear: it could return a list of CustomerDetails objects, or it could return a list of URIs for CustomerDetails objects (which the client can go on to retrieve individually). Both conventions are common.

To implement a Collection in CICS, create a JSON schema that describes either a list of data instances, or a list of URIs. You can then build the Service and implement it as normal. In this example you might choose to only implement the GET method. You could consider implementing a pagination Service to allow a client to page backwards and forwards through large data sets, for example:

GET
/Services/CustomerDetails?startRecord=200&endRecord=225

You're likely to need two URIMAP resources in CICS (and two WEBSERVICE resources). One that maps the root URI structure for the Collection, and a wild-carded URIMAP for the Instances. For example:

URIMAP1: Path=/Services/CustomerDetails 
WEBSERVICE=CollectionService
URIMAP2: Path=/Services/CustomerDetails/* WEBSERVICE=InstanceService