Configuring a REST Resource Using the Legacy Approach

You can use the legacy approach to create a new REST resource that include the REST resource folder and the flow services that correspond to HTTP methods. REST resources generated using the legacy approach are invoked with the rest directive. For information about the procedure to configure REST resources, see the webMethods Service Development Help.

On Integration Server the resources of your application are represented as folders within a package. For each resource, you will write individual services for the HTTP methods that you want Integration Server to execute against the resource. Those services must be named _get, _post, _put, _patch, and _delete, and they are stored in the folder for the resource. For more information, see Setting Up a REST Application Using the Legacy REST Approach.

A simple REST request looks like this:

METHOD /directive/resource_type/resource_id HTTP/1.1

Where...	Is the...
`METHOD`	HTTP request method.
`directive`	The type of processing to perform.
`resource_type/resource_id`	Resource to act upon.

Consider a Discussion application that maintains a database of discussions about different topics. The following examples show how Integration Server would parse these REST requests.

Example 1

Here is a request to obtain a list of all topics contained in the database, and how Integration Server parses the request:

GET /rest/discussion/topic HTTP/1.1

Where...	Is the...
GET	Type of HTTP method to perform. Integration Server maps this value to the corresponding service on Integration Server, in this case, the _get service.
rest	This is a directive which shows the type of processing to perform. In this case, Integration Server REST processing. Note: For more information about directives, see Controlling the Use of Directives.
discussion/topic	Location of the _get service for this resource on Integration Server. In this example, the _get service resides in the topic folder under the discussion folder (discussion.topic).

Example 2

Here is a request to display information about topic number 3419, and how Integration Server parses the request:

GET /rest/discussion/topic/3419 HTTP/1.1

Where... Is...

Where...	Is...
`3419`	This is a `$resourceID`. An instance of a resource passed into a service as the `$resourceID` variable. In the example, the `$resourceID` variable narrows the focus of the GET request to topic 3419. Note: Integration Server assigns the first token after the folder(s) to the `$resourceID` parameter. To determine whether a token represents a folder or the `$resourceID`, Integration Server looks in the current namespace for a folder that has the same name as the token. If it does not find a folder with this name, Integration Server assigns the token to the `$resourceID` variable. In other words, the first token (after the directive) that does not correspond to a folder becomes the `$resourceID`.

3419

This is a $resourceID. An instance of a resource passed into a service as the $resourceID variable. In the example, the $resourceID variable narrows the focus of the GET request to topic 3419.

Note: Integration Server assigns the first token after the folder(s) to the $resourceID parameter. To determine whether a token represents a folder or the $resourceID, Integration Server looks in the current namespace for a folder that has the same name as the token. If it does not find a folder with this name, Integration Server assigns the token to the $resourceID variable. In other words, the first token (after the directive) that does not correspond to a folder becomes the $resourceID.

Example 3

Here is a request to display information about a particular comment, 17 for example, and how Integration Server parses the request:

GET /rest/discussion/topic/3419/comment/17 HTTP/1.1

Where...	Is...
`comment/17`	This is a `$path` variable. Additional information that further narrows the information about the resource. This information is passed into a service as the `$path` variable. In the example, `comment/17` further narrows the focus of the GET request to comment 17.

Example 4

Here is a request to display information contributed by participant Robertson in 2009 about topic 17, and how Integration Server parses the request:

GET /rest/discussion/topic/3419/comment/17?year=2009&name=Robertson HTTP/1.1

Where...	Are...
`year` and `name`	Input variables that are specific to your application. Tokens specified after the ? must be entered as name/value pairs. In this example, `year=2009` and `name=Robertson` narrow the focus of the GET request to entries that participant Robertson added to comment 17 in 2009.

Processing Requests Using Partial Matching of URL Aliases

REST URL requests usually include the identifier for a particular resource. However, because the identifier varies for each instance of a resource, REST requests often do not exactly match any of the defined URL aliases for a particular resource. To enable you to define URL aliases for REST resources, Integration Server can use partial matching to process REST requests. A partial match occurs when a REST request includes only part of a URL alias. For more information about URL aliases, see Creating an HTTP URL Alias.

Note: You can configure URL aliases only for REST resources configured using the legacy approach.

When partial matching is enabled and Integration Server receives a REST request URL, an alias is considered a match if the entire alias matches all or part of the request URL, starting with the first character of the request URL's path.

For example, assume the following URL aliases are defined:

URL Alias	URL Path
a1	rest/purchasing/order
a2	rest/purchasing/invoice
a22	rest/purchasing/admin
a3	invoke/pub.flow/debugLog

When partial matching is enabled, the following request URLs would get different results:

A request URL of http://MyHost:5555/a1 matches URL alias a1 exactly. The resulting URL is http://MyHost:5555/rest/purchasing/order.
A request URL of http://MyHost:5555/a2/75909 matches alias a2 because the request URL's path begins with "a2". The trailing characters of the request URL are retained and the resulting URL is http://MyHost:5555/rest/purchasing/invoice/75909.
A request URL of http://MyHost:5555/a1/75909/customer/0122?terms=net7 matches alias a1 because the request URL's path begins with "a1". The trailing characters of the request URL are retained and the resulting URL is http://MyHost:5555/rest/purchasing/order/75909/customer/0122?terms=net7.

In some cases, a partial match can result in an invalid request. For example, a request URL of http://host:5555/a3456 matches alias a3 because the request URL's path begins with "a3". The trailing characters of the request URL are retained and the resulting URL is http://host:5555/invoke/pub.flow/debugLog456. Since there is no pub.flow:debugLog456 service, this would be an invalid request.

For instructions on enabling partial matching, see Enabling Partial Matching of URL Aliases.