Forwarding REST requests with dynamic routing at the Vordel API Server

Originally posted on, on Monday, July 23rd 2012, by Mark O’Neill, CTO at Vordel

The basics: Forwarding REST requests with dynamic routing at the Vordel API Server

A common basic requirement with the Vordel API Server is to simply forward REST API requests on to an application server. Now, you can do this on an API-by-API basis using the API Service Manager, as shown in the screenshot below.

API Registration






But what if you want to simply map all request on to a back-end application server? You can do this with the following simple steps, configured in Policy Studio:

1) Create a policy called (let’s say) “Forward REST Request”. Drag in a “Static Router” filter first, then right-click on it and choose “Set as start”. In this filter, configure the name of the server you want to route your REST requests to.

"Forward REST Requests"







You can see below that I’ve configured it with the machine name “AppServer” and the port “8080″. If your machine is called “”, this is where you’d configure that.

"Forward REST Request - Image 2"







I follow my “Static Router” filter with a “Connection” filter, which is what actually makes the connection to the back-end REST service.

Side point: The name “Static Router” is perhaps misleading here, because what it does is allow you to *dynamically* route all requests to the back end machine. If a requests comes in to http://APIServer/foo then it will be routed to http://AppServer:8080/foo , and if a request comes in to http://APIServer/bar then it will be routed to http://AppServer:8080/bar . The API Server does not need to know anything in advance about “/foo” or “/bar”.

2) Next, I map my path “/” to the policy I just created. This means that all requests which come through the API Server are forwarded to the AppServer machine you’ve configured.

"Forward REST Request - Image 3"







Common questions:
- “Do I need to configure a Remote Host for the machine I’m routing to?”. Answer: No. You only need to configure a Remote Host if you are doing something special on your connection to the target server, such as (a) connecting over HTTP 1.0 instead of HTTP 1.1, (b) Monitoring it in Analytics, or (c) Load-balancing the connection over a number of back-end machines (e.g. if you wanted the “AppServer” machine traffic to be spread over two IP addresses).

- “Will this work for both REST requests and SOAP also?”. Answer: Yes. If a SOAP request comes in on a HTTP POST, then the API Server will forward this on to the target machine (in this case “AppServer” on port 8080) over HTTP POST also.

- “What does ${env.PORT.TRAFFIC} and Address * mean on the listener under Default Services?”. This means that the API Server is listening on a port which is configured as an environmental variable, read from the envSettings.props file. In this case, the value is 8080, which means it is listening on port 8080. Address “*” means that the API Server is listening on all IP addresses assigned to the machine it is on. If you want to limit it to listening on only one address, this is where you would configure that address.

- “What is the ‘Dynamic Router’ filter for then?”. It is for configuring the API Server to act as a HTTP proxy.

- “What about the ‘Connect to URL filter’?”. That is for connecting to a specific path at the destination. For example, if you wanted requests to always be forwarded to http://appserver:8080/foo no matter what path they came into the API Server on, this is the filter you’d use.

- “What if I want to load-balance the traffic to the target REST service on the app server?”. To do that, you’d use a Remote Host entry for load-balancing, as described in this blog post.

- “How do I test this?”. You can use the free SOAPbox testing tool from Vordel to create a REST request to send to the API Server. Just make sure that you choose the verb “GET” if it’s a HTTP GET request, under “Request Settings” (which you can get to by clicking on the little down-arrow beside the green arrow button on the toolbar). Also, you may need to set the Content-type header correctly under “Headers”, to match what your app server expects (e.g. “Application/json” or “application/x-www-form-urlencoded; charset=UTF-8″). Give your REST request a name (in this case I call it “JSON”) and configure the URL of the API Server you are routing to.