Configuring a REST Resource Using the URL Template-Based Approach
Starting with version 10.0 of Integration Server, you can use the URL template-based approach to configure REST resources for an existing Integration Server service. To configure a resource, you need to specify:
The format of the URL that your applications must follow when sending requests to
Integration Server acting as the REST server. The URL format functions as a template for the application requests to the REST server.
Integration Server attempts to match a request URL received from any application against the URL format defined for a REST resource and determines whether the request URL is valid.
The HTTP methods that the REST resource will support.
The URL template-based approach provides you with greater flexibility than the legacy approach in defining REST resources. For an existing service, you can define multiple REST resources and associate each resource with a URL format of your choice and HTTP methods. In addition, you can edit the URL format associated with a REST resource based on your requirements.
REST resources configured using the URL template-based approach are invoked with the restv2 directive. You can list all the REST resources invoked with the restv2 directive by using the pub.restV2:listAllRESTResources service. For more information, see webMethods Integration Server Built-In Services Reference.
Note: | A REST resource configured using the URL template-based approach cannot be used in a REST API descriptor. |
Considerations for Specifying the URL Format in a REST Resource Configuration
Consider the following while defining the URL format in a REST resource configuration:
A URL format definition can either include only static parameters or a combination of both and static and dynamic parameters. The definition cannot include only dynamic parameters. For example, in the URL format
/restv2/customer/{id}/order/{orderID}, the parameters
customer and
order are static while
{id} and
{eventID} are dynamic.
Enclose dynamic parameters in the URL format within braces (
{}). For example, in the URL format
/restv2/customer/{id}, the
{id} parameter is dynamic and represents an attribute of the customer resource.
While a URL format definition can include multiple dynamic parameters, each dynamic parameter can appear only once.
Wildcard characters are not supported in the definition of a URL format.
Query parameters are not supported in the definition of a URL format. However, the request URL from the client application to
Integration Server can include query parameters at run time.
Ensure that multiple
Integration Server services do not include similarly defined URL formats with the same set of supported HTTP methods. This is because when a client application sends a request URL that matches a defined URL format,
Integration Server might not invoke the required resource because of the availability of multiple services with similarly configured REST resources.
For example, a client request GET /restv2/customer/23 issued to an Integration Server might not invoke the correct REST resource if the Integration Server has two resources defined as follows:
Resource 1
Service:
customerURL Format:
/restv2/customer/{id}Supported HTTP Method:
GETResource 2
Service:
orderURL Format:
/restv2/customer/{cid}Supported HTTP Method:
GETExamples of Configuring REST Resources Using the URL Template-Based Approach
Consider the Discussion application described in
Configuring a REST Resource Using the Legacy Approach. The following examples show REST resources configured using the URL template-based approach and how
Integration Server parses client requests:
Example 1
Consider a REST resource configured with the following URL format:
/restv2/discussion/topic/{id}
Here is a request to display information about a specific topic, and how Integration Server parses the request:
GET /restv2/discussion/topic/236 HTTP/1.1
Where... | Is the... |
GET | HTTP method supported by the resource that is configured for the Integration Server service. Note: | Integration Server treats this method as valid only if the resource and the underlying service are configured to support the GET method. For more information about configuring supported HTTP methods for services, see webMethods Service Development Help. |
|
restv2 | Type of processing to perform, in this case, Integration Server REST processing. Note: | For more information about directives, see webMethods Integration Server Administrator’s Guide. |
|
discussion/topic | Name of the resource on Integration Server. In this example, both discussion and topic are resources. |
236 | Identifier for a topic. Integration Server matches this value against the dynamic parameter {id} specified in the URL format. |
Example 2
Consider a REST resource configured with the following URL format:
/restv2/discussion/topic/t-{id}
Here is a request to display information about a topic based on its identifier, and how Integration Server parses the request:
GET /restv2/discussion/topic/t-1591 HTTP/1.1
Where... | Is the... |
t-1591 | Identifier for a topic. In the URL format specified for this example, t is a static parameter while {id} is a dynamic parameter. Integration Server matches the value t-1591 against the topic identifier parameters specified in the URL format (t-{id}). Note: | In this example, Integration Server treats t-1591 as a valid value considering the URL format specified for the REST resource. However, an identifier that does not follow the specified format, for example, 236 would be considered invalid. |
|
Example 3
Consider a REST resource configured with the following URL format:
/restv2/discussion/topic/t-{id}/comment/{cid}
Here is a request to display information about a particular comment, and how Integration Server parses the request:
GET /restv2/discussion/topic/t-1591/comment/4 HTTP/1.1
Where... | Is the... |
comment/4 | Additional information for the topic with the identifier t-1591. Integration Server matches this value with the portion of the request URL after the topic identifier. The value 4 is matched against the dynamic parameter {cid}. |
