RESTful web services and API design

The primary focus of RESTful web service design is to identify the z/OS® assets that need to be exposed, determine the HTTP methods that you want to support for those assets, and then map the resource identifiers and methods to those assets.

zosConnect-2.0 Applies to zosConnect-2.0.

The methods that are defined by the HTTP specification provide a uniform interface for interacting with resources on the web. All web browsers, servers, and applications understand this uniform interface and the semantics of each operation. They can connect to one another and exchange information by using this uniform interface regardless of platforms or technology differences.

After the resources that need to be exposed for the service are determined, the next step is to design a REST API. This API is the user interface to the consumers of the API. The consumers of the API might be application developers who need to build RESTful clients to access the services, or an integration developer who publishes your APIs in z/OS Connect API.

A REST API describes a set of resources and a set of methods that can be called to act on those resources. The methods in a REST API can be called from any HTTP client, including client-side JavaScript code that is running in a web browser. The REST API has a base path, which is similar to a context root. All resources in a REST API are defined relative to its base path. The base path can be used to provide isolation between different REST APIs. The HTTP client uses a path relative to the base path that identifies the resource in the REST API that the client is accessing. The paths to a resource can be hierarchical, and a well-designed path structure can help a consumer of a REST API understand the resources that are available within that REST API. The following table lists some example resources for a patient database in the REST API:

Table 1. Example resources
Resource	Description
/patients	All of the patients in the database
/patients/12345	Patient #12345
/patients/12345/orders	All prescription orders for patient #12345
/patients/12345/orders/67890	Prescription order #67890 for patient #12345

Each resource in the REST API has a set of methods that can be called by an HTTP client. The following table lists example methods for the resource /patients/12345:

Table 2. Example operations
HTTP Method	Description
GET	Retrieve the patient details from the database.
PUT	Update the patient details in the database.
DELETE	Delete the patient from the database.

To update information for that patient, the HTTP client would make an HTTP PUT request to /patients/12345.

With a uniform interface for communication, application developers can focus on the resources rather than the methods. They can create their applications without having to deal with a complex system or learn the intricacies of new interfaces. They can also freely change their applications while the communication methods that connect to these resources remain stable.

Each path and method combination in a REST API can also have a set of parameters that can be used by the HTTP client to pass arguments. Each parameter must be defined in the definitions for the REST API. Each parameter has a unique name and type. Several types of parameters are supported by REST APIs in IBM® z/OS Connect:

Path parameters: Can be used to identify a particular resource. The value of the parameter is passed in by the HTTP client as a variable part of the URL, and the value of the parameter is extracted from the path for use in the operation. Path parameters are denoted by using the syntax {paramName} in the path to the resource. For example, the patient ID can be passed in as a path parameter named patientID:
/patients/{patientID}
Query parameters: The value of a query parameter is passed in by the HTTP client as a key-value pair in the query string at the end of the URL. As an example, query parameters can be used to pass in a minimum and maximum number of results to be returned by a particular call:
/patients?min=5&max=20
Header parameters: The HTTP client can pass header parameters by adding them as HTTP headers in the HTTP request. As an example, a header parameter might be used to pass in a unique identifier that identifies the HTTP client that is calling the API:
Api-Client-Id: fffe2c5d-42d5-7428-5f5f-abc34ab7f555

To assist you with the design and development of this API, IBM z/OS Connect provides a graphical editor, the z/OS Connect API toolkit.

Designing APIs for use with interceptors

Service interceptors are not called for API requests. Interceptors that are configured for services are only triggered if the service is invoked directly from an HTTP or HTTPS request. They are not triggered if the service is invoked from an API.

Consider the following criteria when designing your APIs to work with interceptors:

You should only combine services that have the same security constraints (authorization and audit) into a single API. For example, do not combine getBalance and accountTransfer services into the same API if the authorization or audit requirements of these banking services are different.
You should only combine services that have the same logging constraints into a single API.
You should only combine services into a single API if API-level monitoring is sufficient. For example, you want to monitor the number of API requests to an account but not the number of balance inquiries, postings, or transfers.