Oracle® Fusion Middleware
Part 7. API Gateway Instances

A Relative Path binds policies to a specific relative path location (for example /test/path). When the API Gateway receives a request on the specified Relative Path, it invokes the specified policy or policy chain. This topic explains how to configure Relative Path resolvers. For details on how to configure policies, see Part 4, “Policy Governance”.

You can use a Static Content Provider or Static File Provider to serve static HTTP content or files from a particular directory. In this case, the API Gateway instance acts as a Web server. The API Gateway instance can also act as a Servlet Application container, which enables you to drop servlets into the HTTP Services configuration. This should only be used by developers with specific requirements under strict advice from the Oracle Support team.

Relative Paths can have nested child resolvers of the following type:

This topic explains how to use the Policy Studio to configure each of these Relative Path resolver types. For details on configuring HTTP Services Groups and HTTP Interfaces, see Configuring HTTP Services.

To configure a Relative Path for a specific HTTP Service Group (for example, Default Services), perform the following steps:

Alternatively, when editing a policy, you can click the Add Relative Path button at the bottom of the policy canvas beside the Context drop-down list.

The next four sections explain how to configure the settings on the Configure Relative Path dialog.

Use the Policies tab to specify the Relative Path and the policies that are called. The API Gateway invokes the selected policies when it receives a request on the specified path. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. Complete the following fields:

When you select multiple policies to form a policy chain, the behavior is the same as for a policy shortcut chain filter. Policies are only evaluated when selected, and when the policy can be reached. If any reachable policy fails, the chain fails, and no more policies are evaluated.

The Audit Settings tab enables you to configure the logging level for all filters executed on the Relative Path, and to configure when message payloads are logged.

Logging Level

You can configure the following settings on all filters executed on the specified Relative Path:

For more details on logging levels, and on how to configure logging for a specific filter, see the Transaction Log Level and Message topic.

Payload Level

You can configure the following settings on the specified Relative Path:

For details on how to log message payloads at any point in a specific policy, see the Log Message Payload topic.

Access Log

Select the Include in server access log records setting if you wish to add this Relative Path to the API Gateway Access Log. This enables the Access Log at the service level. This setting is not selected by default. For more details, see the topic on Access Log Settings.

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for the Relative Path from the list.

You can also configure multiple HTTP methods on paths of the same name. This enables you to call different policies for different HTTP methods, as shown in the following example:

In this example, the /test path is configured three times, each using a different HTTP Method as follows:

For details on the subpath shown in this example (Path/Test1), see the section called “Nested Relative Paths”.

On the Advanced tab, select whether to resolve this Relative Path using an Exact path match. The default behavior is to use a longest path match (explained in the next section). This setting enables you to further restrict the match to an exact path match (for example, test1/helloService). This setting is not selected by default.

Using the example shown in the section called “HTTP Method Settings”, when you have a path / that has a child subpath (in this case /test1), the following occurs when a request arrives at the API Gateway:

From a policy execution point of view, when the request is being processed, each policy associated with a matching path is executed. In the above example, both / and /test1 make up the match. This means that the policy associated with / is executed first, and if that passes, the policy associated with /test1 is executed. The parent policy uses the Call Internal Service filter, which enables child resolvers to be invoked.

Nested paths are generally used as a protection mechanism. For example, a system might be configured with / as the only root path, with a number of children. / could have a Role-Based Access Control (RBAC) policy associated with it protecting all children. If the RBAC policy succeeds, access is granted, and the child policy is executed. If it fails, access is denied. This mechanism is implemented in the Admin Node Manager. You can view this in Policy Studio by opening the Admin Node Manager configuration.

Adding a Nested Relative Path

To add a child node to a Relative Path, right-click the appropriate Relative Path node in the Resolvers screen, and select the node type (for example, Add -> Relative Path). You can add child resolver nodes of the following type:

In the following example, there is one main Relative Path configured to /, which calls the Protect policy. Content is served by the underlying Servlet Application and Static Content resolvers only when the Protect policy succeeds:

Order of Resolution

The order of resolution for nested Relative Paths is to first resolve at the parent level. If resolution is successful, and there are children present, then attempt to resolve at the child level. There is no precedence between resolver node types (Relative Path, Static Content Provider, and Servlet Application). Path resolution is performed using the longest path match algorithm by default, regardless of whether nested subpaths are used. For details on configuring an exact path match, see the section called “Advanced Settings”.

Example Nested Path Resolution

Using the example Relative Path in the screen above, consider the following inbound requests to the Node Manager:

https://testpc:8090/api/deployment/domain/deployments
https://testpc:8090/common/themes/blue/images/server_icon.png

The /api/deployment/domain/deployments request is resolved as follows:

In this example, there are two matches, the api Servlet under the Servlet Application on /, and the Static Content on /. Because the API Gateway uses the longest path match, the api Servlet wins, and the request is routed to that resolver. There is no precedence between resolvers, all resolvers are queried for a match.

The /common/themes/blue/images/server_icon.png request is resolved as follows:

In this example, there is only one match, the Static Content on /. In this case, the Servlet Application on / is not considered because none of its children can resolve the request path.

A Static Content Provider can be used with an HTTP Interface to serve static content from a specified directory. A Relative Path is associated with each Static Content Provider so that requests received on this path are dispatched directly to the provider and are not mapped to a policy in the usual way. For example, you can configure a Static Content Provider to serve content from the c:\docs folder on Windows when it receives requests on the Relative Path /docs.

Adding a Static Content Provider

To add a Static Content Provider to an HTTP Services group (for example, Default Services), perform the following steps:

Relative Path:

Enter the path that you want to receive requests for static content on.

Content Directory:

Enter or browse to the location of the directory that you want to serve static content from.

Index File:

Enter the name of the file that you want to use as the index file for content retrieved from the directory specified in the field above. This file is retrieved by default if no resource is explicitly specified in the request URI. For example, if the client requests http://[HOST]:8080/docs (with only a relative path specified instead of a specific resource), the file specified here will be retrieved. This file must exist in the directory specified in the previous field.

Allow Directory Listings:

If this option is selected, the Static Content Provider returns full directory listings for requests specifying a Relative Path only. For example, if this is selected, and if a request is received for http://[HOST]:8080/docs/samples, the list of directories under this directory is returned, assuming that this directory exists on the file system. You can turn this off to prevent attacks where a hacker can send up different request URIs in the hope that the server returns some information about the directory structure of the server.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for this resolver from the list. For more details, see the section called “HTTP Method Settings”.

A Static File Provider can be used with an HTTP Interface to serve a static file from a specified directory. A Relative Path is associated with each Static File Provider so that requests received on this path are dispatched directly to the file provider and are not mapped to a policy in the usual way. For example, you can configure a Static File Provider to serve c:\my_brand\favicon.ico on Windows when it receives requests on the /favicon.ico Relative Path.

Adding a Static File Provider

To add a Static File Provider to an HTTP Services group (for example, Default Services), perform the following steps:

Relative Path:

Enter the path that you want to receive requests for the static file on (for example, /favicon.ico).

File:

Enter or browse to the location of static file that you want to serve (for example, $VDISTDIR/webapps/emc/favicon.ico, where $VDISTDIR specifies the directory in which the API Gateway is installed).

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method for the static file. The default is GET, which means that only HTTP GET calls are accepted. You can override the default behavior, and select a different HTTP method for this resolver from the list. For more details, see the section called “HTTP Method Settings”.

Developers may wish to write their own Java servlets and deploy them under the API Gateway to serve HTTP traffic. Conversely, they may wish to remove some of the default servlets from the out-of-the-box configuration (for example, to remove the ability to view logging remotely). This pairing down of unwanted functionality may be required to further lock down the machine on which the API Gateway is running.

When editing Admin Node Manager or API Gateway Analytics configuration, there are some default Servlet Applications available under the Management Services group. By default, this HTTP Services Group is not displayed, but can be displayed using the Preferences dialog in the Policy Studio. For example, the /configuration/ Servlet Application updates configuration information for the API Gateway.

Adding a Servlet Application

To add a Servlet Application to an HTTP Services Group (for example, Default Services), perform the following steps:

Relative Path:

Enter the servlet context in this field. You can add multiple servlets under this context, where each servlet is mapped to a unique URI.

Session Timeout:

Enter the timeout in seconds after which an inactive session is closed. Click OK.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for this resolver from the list. For more details, see the section called “HTTP Method Settings”.

Adding a Servlet

The new Servlet Application now appears in the Resolvers screen. To add a new servlet, right-click the new Servlet Application, and select Add Servlet. Configure the following fields on the Servlet dialog:

URI:

The path entered here maps incoming requests on a particular request URI to the Java servlet class entered in the field below. This path must be unique across all Servlets that are added under this Servlet Application (servlet context).

Class:

Enter the fully qualified class name of the servlet class. You can add this class to the server runtime by adding the JAR, class file, or package hierarchy to the [VDISTDIR]/ext/lib folder. VDISTDIR is your API Gateway distribution directory, which is the location where the API Gateway is installed.

Read Timeout:

Specify the time in seconds that the servlet should wait before closing an idle connection.

Servlet Properties:

You can configure properties for each servlet by clicking the Add button, and entering a name and value in the fields provided on the Properties dialog.

A Web Service Resolver is used to identify messages destined for a Web Service, and to map them to the Service Handler (Web Service Filter) for that Web Service. When you import a WSDL file in the Web Service Repository, a new Web Service Resolver node is created for each imported Web Service under the Paths for the relevant HTTP Services group (for example, Default Services). You can edit the Web Service Resolver settings by right-clicking its tree node, and selecting Edit.

The following settings are available in the Web Service Resolver dialog:

Enable this web service resolver:

Specify whether to enable this Web Service resolver. This is enabled by default.

Name:

You can edit the name of the Web Service Resolver.

Web Service:

Click the browse button to select a Web Service to resolve to. Defaults to the Web Service imported into the Web Services Repository when this resolver was created.

Policies:

On the Policies tab, select the path and the policies to use for the Web Service. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. The global request policy, the policy automatically generated when the WSDL file is imported, and the global response policy are all selected in a chain by default. Complete the following fields:

Policies are only evaluated when selected, and when the policy can be reached. If any selected policy fails, the chain fails, and no more policies are evaluated.

Audit Settings:

The Audit Settings tab enables you to configure the logging level for all filters executed on the Web Service, and to configure when message payloads are logged. The default logging level for all filters on the Web Service is Failure. These logging settings are the same as those already described for the Relative Path. For more details, see the section called “Audit Settings”.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method from the list. The HTTP Method settings are the same as those already described for the Relative Path. For more details, see the section called “HTTP Method Settings”.

Editing Service Handler Options

You also edit options for the Service Handler for the Web Service. Right-click the Web Service Resolver node, and select Quick-Edit Policy to display a dialog that enables you to configure the following options:

These options enable you to configure the underlying auto-generated Service Handler (Web Service Filter) without navigating to it in the Policies tree. These are the most commonly modified Web Service Filter options after importing a WSDL file. Changes made in this dialog are visible in the underlying Web Service Filter. For more details, see the Web Service Filter topic.