HTTP Method/Path

The mechanism used by Enterprise Server to call a Web service differs with JSON (RESTful) Web services from that of other service types in that Enterprise Server uses the request URI as the means of ascertaining the operation requested. For other types of requests, such as SOAP requests, it extracts the operation name from the body of the request.

For each JSON (RESTful) service interface operation, the relative path portion of the request URI, along with the method defined for the operation, are defined on the Operation Properties - HTTP tab.

Operations for the same logical resource are typically defined with the same path but with a different HTTP method; thus an operation is uniquely identified by its path-method combination.

If Enterprise Server were to receive a JSON request that has no indicated operation, for example, a GET request consisting of a base URI only, this returns a special response message of a single array of JSON Link Description Objects containing the relative URI paths for all the operations defined for the service. This enables a client to "discover" how to access the operations for the base URI without having to provide any operation names.

Method

Each operation is assigned one of the following methods, each of which corresponds to a standard HTTP method:

GET: Typically used to retrieve the resource identified by the specified URI.
POST: Typically used to create a new resource using the specified URI. Default.
PUT: Typically used to update the resource identified by the specified URI.
DELETE: Typically used to delete the resource identified by the specified URI.

Path

The relative URI path, when appended to the base URI for a JSON (RESTful) service is used to invoke an operation.

In the context of a JSON (RESTful) service, a relative path is a representation of an API resource derived from the COBOL code, and serves as the name by which Enterprise Server identifies the operation.

The default relative path for any operation is /operationName.

Variable portions of a path are represented by a parameter name enclosed in braces ({}). For example:

/cars/{make}/parts

The parameter {make} represents the value in any occurrence of the field.

Important: If a JSON Web service has two or more operations with ambiguous path-methods, then Enterprise Server invokes the operation that appears first in the service as defined. For example, the following paths are ambiguous:

/cars/{make}/parts
/cars/{model}/parts

As are these, because the URI /cars/ford/parts is valid for both paths:

/cars/{make}/parts
/cars/ford/parts

Therefore, take care when defining operation paths to avoid ambiguity.