Operations

Once you have initially created the service interface, you define its functionality by creating a collection of operations using the Interface Mapper. Generally, an operation represents an interaction with a single program entry point. In the Interface Mapper, you work with one operation at a time.

A single service interface typically contains multiple operations. For example, if you know that a single entry point leads to an EVALUATE statement choosing between different functions, you could define a separate operation for each one of these functions. Often in such a program, one parameter is a parameter tested by the EVALUATE statement to see which function is specified.

For deployment purposes, all operations are packaged together into one service, but each operation is independently executable (i.e., only one operation is invoked per service execution).

A deployed operation's name is used by Enterprise Server for identification purposes (as described in the topic Service Names and Operations). For incoming SOAP Web service requests, Enterprise Server ascertains which operation to invoke by extracting the operation name from the body of the request (note, not from the URI of the request). In contrast, for JSON (RESTful) Web service requests, the request URI is used as the means of ascertaining the operation requested, as described below.

Operation paths

In the Interface Mapper, for JSON (RESTful) Web services, an operation can be given a relative URI path (default /operationName), which, prepended with the service's base URI, is used to invoke that operation. Any variable portions of a path can have a parameter name enclosed in braces, for example /cars/{make}/parts. Operations for the same logical resource are typically defined with the same path but with a different HTTP method (i.e. GET, POST, PUT, DELETE). Thus an operation is uniquely identified by its path-method combination. If a JSON Web service has two or more operations with ambiguous path-methods, Enterprise Server will invoke the operation that appears first in the service as defined. An example of ambiguous paths is /cars/{make}/parts and /cars/{model}/parts, or even /cars/{make}/parts and /cars/ford/{model} (because the URI /cars/ford/parts is valid for both paths). Therefore, take care when defining operation paths, to avoid ambiguity. If Enterprise Server receives a GET request comprising just the base URI of a JSON Web service (i.e. no operation is indicated), a special response message is returned comprising a single array of JSON Link Description Objects containing the relative URI paths for all the operations of the service. This way, a client only ever needs to know a service's base URI and can "discover" how to access its operations.

Generating operations for API resources

For JSON (RESTful) Web services, when creating a new operation, there is an option to automatically identify "API Resources" from COBOL group structures within the chosen entry point and generate a set of new operations all at once. You can choose which identified resources you want to generate operations for, the relative URI path for a resource's operations, and the HTTP methods that can be used to access the resource, resulting in a new operation for each of the chosen HTTP methods of the chosen resources.