Getting Started with Routing Configuration

Overview

This topic describes how to configure the API Gateway to send messages to external Web services. The API Gateway offers a number of different filters that can be used to route messages. Depending on how the API Gateway is perceived by the client, different combinations of routing filters can be used.

For example, the API Gateway can act both as a proxy and as an endpoint (in-line) server for a client, depending on how the client is configured. In each case, the request received by the API Gateway appears slightly different, and the API Gateway can take advantage of this when routing the message onwards. Furthermore, the API Gateway can provide service virtualization by shielding the underlying hierarchy of back-end Web services from clients.

This topic explains how clients can use the API Gateway both as a proxy and as an endpoint server. It then shows how service virtualization works. When these basic concepts are explained, this topic helps you to identify the combination of routing filters that is best suited to your deployment scenario.

Proxy or Endpoint Server

The API Gateway can be used by clients as both a proxy server and an endpoint server. When a client uses the API Gateway as a proxy server, it sends up the complete URL of the destination Web service in the HTTP request line. The API Gateway can use the URL to determine the host and port to route the message to. The following example shows an HTTP request received by the API Gateway when acting as a proxy for a client:

POST http://localhost:8080/services/getHello HTTP/1.1

Alternatively, when the API Gateway is acting as an endpoint (in-line) server, the client sends the request directly to the API Gateway. In this case, the request line appears as follows:

POST /services/getHello HTTP/1.1

In this case, only the path on the server is specified, and no scheme, host, or port number is included in the HTTP request line. Because this information is not provided by the client, the API Gateway must be explicitly configured to route the message on to the specific destination.

Service Virtualization

It is sometimes desirable to shield the underlying structure of the directory hierarchy in which Web services reside from external clients. You can do this by providing a mapping between the path that the client accesses and the actual path at which the Web service resides.

For example, suppose you have two Web services accessible at the /helloService/getHello and /financeService/getQuote URIs. You may wish to hide that these services are deployed under different paths, perhaps exposing them under a common /services base URI (for example, /services/getHello and /services/getQuote). The client is therefore unaware of the underlying hierarchy (for example, directory structure) of the two Web services. This is termed service virtualization.

Choosing the Correct Routing Filters

This section first identifies how your clients perceive the API Gateway, and then determines whether you wish to virtualize your back-end Web services. Depending on these requirements, you can use different combinations of routing filters, as described in the use cases in the subsequent sections.

Consider the following to determine which combination of routing filters is most appropriate for your scenario:

Proxy or Endpoint?

  • If the client is using the API Gateway as a proxy server, see cases 1 or 2 below, depending on whether service virtualization is required.

  • Alternatively, if the client using the API Gateway as the endpoint of the connection (as an in-line server), see cases 3 or 4 below.

Service Virtualization?

  • If you want to shield the hierarchy of protected Web services by exposing a virtual view of these services, see cases 2, 4, and 5 below.

  • If service virtualization is not important, see cases 1 and 3 below.

These permutations are summarized in the following table:


Case 1: Proxy without Service Virtualization

In this case, the API Gateway is configured as an HTTP proxy for the client, and maintains the original path used by the client in the HTTP request. For example, if the API Gateway is listening at http://localhost:8080/, and the Web service is running at http://localhost:5050/services/getQuote, the request line of the client HTTP request appears as follows:

POST http://localhost:5050/services/getQuote HTTP/1.1

Because the client is configured to use the API Gateway instance running on localhost at port 8080 as its HTTP proxy, the client automatically sends all messages to the proxy. However, it includes the full URL of the ultimate destination of the message in the request line of the HTTP request.

When the API Gateway receives the request, it extracts this URL from the request line and uses it to determine the destination of the message. In the above example, the API Gateway routes the message on to http://localhost:5050/services/getQuote.

You can configure the following policy to route the message to the URL specified in the request line of the client request:

Policy 1: Proxy without Service Virtualization

The following table explains the role of each filter in the policy. For more information on a specific filter, click the appropriate link in the Details column.

Filter Role in Policy Details
Dynamic Router Extracts the URL of the destination Web service from the request line of the incoming HTTP request. The Dynamic Router is normally used when the API Gateway is perceived as a proxy by the client. Dynamic Router
Connection Establishes the connection to the destination Web service, and sends the message over this connection. This connection can be mutually authenticated if necessary. Connection


Case 2: Proxy with Service Virtualization

In this case, the API Gateway is also perceived as an HTTP proxy by the client. However, the API Gateway exposes a virtualized view of the services that it protects. This is termed service virtualization.

To achieve this, the API Gateway must provide a mapping between the path used by the client and the path under which the service is deployed. Assuming the API Gateway is running at http://localhost:8080/services, and the Web service is deployed at http://localhost:5050/financialServices/quotes/getQuote, the following example shows what the client may send up in the HTTP request line:

POST http://localhost:5050/services/getQuote HTTP/1.1

To achieve this, the API Gateway must provide a mapping between what the client requests (/services/getQuote), and the address of the Web service (/financialServices/quotes/getQuote. The Rewrite URL filter in the following policy fulfills this role:

Policy 2: Proxy with Service Virtualization

The following table explains the roles of the each filter in the policy:

Filter Role in Policy Details
Dynamic Router Extracts the URL of the destination Web service from the request line of the incoming HTTP request. The Dynamic Router is normally used when the API Gateway is perceived as a proxy by the client. Dynamic Router
Rewrite URL Specifies the mapping between the path requested by the client and the path under which the Web service is deployed, therefore providing service virtualization. Rewrite URL
Connection Establishes the connection to the destination Web service, and sends the message over this connection. This connection can be mutually authenticated if necessary. Connection


Case 3: Endpoint without Service Virtualization

In this scenario, the client sees the API Gateway as the endpoint to its connection, and the API Gateway must be configured to route messages on to a specific destination. For example, assuming that the API Gateway is running at http://localhost:8080/services, the request line of the client's HTTP request is received by the API Gateway as follows:

POST /services HTTP/1.1

The request line above shows that no information about the scheme, host, or port of the destination Web service is specified. Therefore, this information must be configured in the API Gateway so that it knows where to route the message on to. The Static Router enables the user to enter connection details for the destination Web service.

Assuming that the Web service is running at http://localhost:5050/stockquote/getPrice, the host, port, and scheme respectively are: localhost, 5050, and http. You must explicitly configure this information in the Static Router. The following policy illustrates this scenario:

Policy 3: Endpoint without Service Virtualization

The following table explains the role of each filter in the above policy:

Filter Role in Policy Details
Static Router Enables the user to explicitly specify the host, port, and scheme at which the Web service is listening. This filter must be used when the client sees the API Gateway as the endpoint to its connection (the API Gateway is not acting as a proxy for the client). Static Router
Connection Establishes the connection to the destination Web service, and sends the message over this connection. This connection can be mutually authenticated if necessary. Connection


Case 4: Endpoint with Service Virtualization

In this case, the API Gateway acts as the endpoint to the client connection (and not as a proxy), and hides the deployment hierarchy of protected Web services from clients (performs service virtualization).

In this scenario, the client sends messages directly to the API Gateway. For example, assuming that the API Gateway is running at http://localhost:8080/services, and the Web service is running at http://localhost:5050/stockquote/getPrice, the request line of the client HTTP request is received by the API Gateway as follows:

POST /services HTTP/1.1

You can then configure the Static Router filter to route the message on to port 8080 on localhost using the http scheme, while the Rewrite URL filter provides the mapping between the path requested by the client (/services) and the path under which the Web service is deployed (/stockquote/getPrice). The following policy illustrates a sample policy that provides service virtualization when the API Gateway is used as an endpoint:

Policy 4: Endpoint with Service Virtualization

The following table explains the role of each filter in the policy:

Filter Role in Policy Details
Static Router Enables you to explicitly specify the host, port, and scheme at which the Web service is listening. This filter can be used when the client sees the API Gateway as the endpoint to its connection (not as a proxy for the client). Static Router
Rewrite URL Provides the mapping between the path requested by the client and the path under which the Web service is deployed. Rewrite URL
Connection Establishes the connection to the destination Web service, and sends the message over this connection. This connection can be mutually authenticated if necessary. Connection


[Important] Important

Alternatively, instead of using the Static Router, Rewrite URL, and Connection filters, you can use the Connect to URL filter, which is equivalent to using these three filters combined. You can configure the Connect to URL filter to send messages to a Web service simply by specifying the destination URL. For more details, see the Connect to URL topic.

Case 5: Simple Redirect

In some cases, the API Gateway must route the incoming message to an entirely different URL. You can use the Rewrite URL filter for this purpose, in addition to rewriting the path on which the request is received (as described in cases 2 and 4 above).

[Note] Note

The full URL of the destination Web service should be specified in the Rewrite URL filter.

The following policy illustrates the use of the Redirect URL filter to route messages to a fully qualified URL:

Policy 5: Simple Redirect

The following table describes the role of each filter in the policy:

Filter Role in Policy Details
Rewrite URL Used to specify the fully qualified URL of the destination Web service. Rewrite URL
Dynamic Router In this case, the Dynamic Router filter is used to parse the URL specified in the Rewrite URL filter into its constituent parts. The HTTP scheme, port, and host of the Web service are extracted and set to the internal message object for use by the Connection filter. Dynamic Router
Connection Establishes the connection to the destination Web service, and sends the message over this connection. This connection can be mutually authenticated if necessary. Connection


Case 6: Routing on to an HTTP Proxy

This is a more advanced case where the API Gateway is configured to route on through an HTTP proxy to the back-end Web service sitting behind the proxy. When the API Gateway is configured to route through a proxy, it connects directly to the proxy, and sends a request including the full URL of the target Web service in the HTTP request URI. When the HTTP proxy receives this request, it uses the URL in the request line to determine where to route the message to. The following example shows the request line of a request made through a proxy:

POST http://localhost:8080/services/getQuote HTTP/1.1

The following filters are required to configure the API Gateway to route through an HTTP proxy:

Filter Role in Policy Details
Static Router You must explicitly specify the host, port, and scheme of the HTTP proxy. Static Router
Rewrite URL Enter the full URL of the Web service (for example, http://HOST:8080/myServices). Because you are routing through a proxy, the full URL is sent in the request line of the HTTP request. Rewrite URL
Connection In this case, the Connection filter connects to the HTTP proxy, which in turn routes the message on to the destination server named in the request URI. The Send via Proxy option must be enabled in the Connection filter to facilitate this. Connection


[Note] Note

Note the differences between how the filters are configured to route on through a proxy and the scenario described in Case 4: Endpoint with Service Virtualization where no proxy is involved:

  • Static Router:

    When the API Gateway routes on to an HTTP proxy, the Static Router filter is configured with the details of the HTTP proxy. Otherwise, the Static Router filter is given the details of the Web service endpoint directly.

  • Rewrite URL:

    The full URL of the Web service endpoint must be specified in this filter when the API Gateway routes through a proxy. The full URL is then included in the request line of the HTTP request to the proxy. In cases where no proxy is involved, the Rewrite URL filter is only necessary when the back-end Web services are virtualized. In this case, the API Gateway must send the request to a different URI than that requested by the client.

  • Connection:

    When routing through a proxy, the Send via Proxy option must be enabled in the Connection filter. This is not necessary when no proxy sits between the API Gateway and the back-end Web service.

Summary

The following are the key concepts to consider when configuring the API Gateway to connect to external Web services:

  • The Connection or Connect to URL filter must always be used because it establishes the connection to the Web service.

  • Service virtualization can be achieved using the Rewrite URL or Connect to URL filter.

  • If the client is configured to use the API Gateway as a proxy, the API Gateway can use the Dynamic Router filter to extract the URL from the request line of the HTTP request. It can then route the message on to this URL.

  • If the client sees the API Gateway as the endpoint of the connection (not as a proxy), the Static Router filter can be used to explicitly configure the host, port, and scheme of the destination Web Service. Alternatively, you can use the Connect to URL to specify a URL.