Working with REST V2 Resource Operation

Defining a REST V2 Resource Operation

To define an operation of a REST V2 resource, you must specify the following:

The format of the URL that REST clients must follow in their requests to Integration Server as the REST server.

The supported HTTP methods.

The associated service.

Important:
An operation in a REST V2 resource should be unique, the combination of a URL template and the supported HTTP method must be unique and unambiguous. This ensures that a single operation always points to a single service.

Example 1

The following URL templates are ambiguous.

URL Template	Runtime URL
GET /product/{pid}	GET /product/101
GET /product/{productCode}	GET /product/101

In the above example, both the URL templates are similar and the corresponding runtime URLs are same. This creates an ambiguity. Integration Server evaluates this ambiguity while adding the URL templates and does not save the REST V2 resources. Similarly, it does not save resources associated with ambiguous URL templates that have different HTTP methods.

Example 2

The following URL templates are unambiguous.

URL Template	Runtime URL
GET /product/{pid}	GET /product/101
GET /product/code/{productCode}	GET /product/code/101

Example 3

The following URL templates are unambiguous even through the runtime URLs are same.

URL Template	Runtime URL
GET /product/{pid}/category/{catId}	GET /product/PD1/category/CD1
GET /product/PD1/{category}/CD1	GET /product/PD1/category/CD1

The above two URL templates are not ambiguous, but the runtime URLs are same. Integration Server resolves this case by matching the static part of the URL template. Since both the URL templates are matched, Integration Server matches the static part first which is /product/PD1 in the second URL template and hence the service mapped to the second URL is invoked. Even though the client intends to invoke the operation corresponding to the first URL template, Integration Server invokes the operation corresponding to the second URL template. Therefore, it is recommended that as a provider of REST services, you must define unambiguous URL templates.

Note:
When you add REST V2 resources to a RAD, Integration Server evaluates the ambiguity for URL templates since two REST V2 resources may have URL templates that are same or ambiguous and does not save the REST V2 resources.

You can associate either a new service or an existing service to a resource operation. Consider the following while associating a service to a REST V2 resource operation:

If you want to associate an existing service to a REST V2 resource operation, you must ensure that the dynamic parameter that you specify in the URL template already exists as a variable of type String in the input signature of the particular service. The service that you select need not reside in the same folder as the REST V2 resource.

If you rename a service associated with REST V2 resource operations and update its references, the impacted resource operations also are updated with the new name of the service.

If you delete a service associated with a REST V2 resource operation or if you delete the input variable that is also referenced in the dynamic parameter of the URL template, the operation will not work when invoked by any subsequent client request to Integration Server.

Consider the following while defining the URL template in a REST V2 resource operation:

A URL template definition is a combination of static path segments and dynamic parameters. For example, in the URL template /rad/cust:customerNode/customer/{id}/order/{orderID}, customer and order are static path segment while {id} and {orderID} are dynamic.

Enclose dynamic parameters in the URL template within braces ({}). For example, in the URL template /rad/customer/{id}, the {id} parameter is dynamic and represents an attribute of the customer resource.

Any dynamic parameter that you specify in a URL template must be available as a variable of type String in the input signature of the flow service associated with the resource operation. If you specify the option of creating a new flow service when defining the resource operation, a new service with the specified name is automatically created under the services folder with the dynamic parameter in the URL template added to the input signature.

Note:
You must create REST API descriptors so that you can expose the REST V2 resources as REST applications. For information about creating REST V2 resources, see Configuring a REST V2 Resource and to create REST API descriptors see Creating a Provider REST API Descriptor from a REST Resource.

While a URL template definition can include multiple dynamic parameters, each dynamic parameter can appear only once in the URL template.

A URL template cannot include the following characters: & ; ? @ # | [ ]

Query parameters are not supported in the definition of a URL template. However, the request URL from the client application to Integration Server can include query parameters at run time.

Ensure that the resource operations in a REST V2 resource are unique, which is a combination of URL template and the HTTP method.

You can define a logical representation of a resource that is associated with the REST V2 resource.

You can define attributes for the REST V2 resource.

You can define relationships between REST V2 resources so that using a single resource all related resources can be accessed.

Important:
To invoke REST APIs, Software AG recommends that you create REST API descriptors.

To define a REST V2 resource operation

1. In the Package Navigator view of Designer, double click the REST V2 resource for which you want to define the operation.

2. On the Resource Configuration tab, click Add.

3. In the Add REST Resource Operation dialog box, specify the following:

Field	Description
REST URL	The URL template that a request from a client application must follow.
Service Name	The name of the service to associate with the REST V2 resource operation. You can specify a service name in either of the following ways: Browse and select an existing service. Specify the fully qualified name of an existing service. Specify the name of a new service.
HTTP Methods	Select one or more HTTP methods for the REST V2 resource operation. Note: For a resource operation, you can select only from the HTTP methods that are supported for the associated service. For information about configuring the supported HTTP methods for an Integration Server service, see Run Time Properties for Services.

4. Click File > Save.

Integration Server validates the details specified for defining the new REST V2 resource operation. If the validation is successful, the new resource operation is added to the Resource Configuration tab. Otherwise, Designer shows details of the validation errors, which you must fix before attempting to save the resource operation details again.

Notes:

If you specify a new service name for associating with the REST V2 resource operation, Integration Server creates a service (Flow, Java, C, or Adapter service) and adds it to the same folder as the REST V2 resource when saving the resource operation. In addition, the input signature of the new service includes the dynamic parameter specified in REST URL.

You can edit the details of an existing REST V2 resource operation by selecting it on the REST V2 Resource Operation tab and clicking Edit.