Retrieving availble HTTP methods from a back-end server through WSO2 ESB APIs

Assume you have a set of back-end servers that supports different combinations of HTTP methods and you have a need to retrieve which server supports what methods. This can be achieved using WSO2 ESB with the help of an API. Lets see how this can be done using a simple example.

Pre-requisites

• Download the latest version of WSO2 ESB distribution (WSO2 ESB) to a preferred location on you file system.
• Download an instance of WSO2 Application Server (WSO2 AS) distribution to host your web application. I will be using version 5.0.1 in this example.

Step 1 - Deploying the web application in WSO2 AS.

Extract the WSO2 AS distribution to a preferred location and start the server. Follow the instructions in the guide Deploying JAX-WS and JAX-RS Applications and deploy the sample web application.

Step 2 - Creating the API in WSO2 ESB

Now lets create an API pointing to the above web application to retrieve it's HTTP methods.

Follow the instructions given under Adding APIs in the Management Console and add an API with the below configuration.


<api xmlns="http://ws.apache.org/ns/synapse" name="CustomerAPI" context="/customer">
   <resource methods="POST GET DELETE PUT" url-mapping="/*">
      <inSequence>
         <send>
            <endpoint>
               <address uri="http://localhost:8280/proxyapi"></address>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send></send>
      </outSequence>
   </resource>
</api>


Step 3 - Invoking the API to retrieve the available methods of the back-end service.

$ curl -v -X OPTIONS http://localhost:8280/customer/customerservice


When you invoke the above curl command, it would return you all the available methods as below.


* About to connect() to localhost port 8281 (#0)
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8281 (#0)
> OPTIONS /customer/customerservice HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8280
> Accept: */*
>
< HTTP/1.1 200 OK
< Max-Forwards: 1
< Host: 127.0.0.1:8280
< Allow: POST,GET,DELETE,PUT,OPTIONS,HEAD
< Accept: */*
< Date: Fri, 25 Apr 2014 13:09:10 GMT
< Server: WSO2-PassThrough-HTTP
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact

This is a simple scenario where there is only one layer between your back-end server and your client (which is the API). But assume that the message flows through another API/proxy service before reaching the back-end and still you need to get the methods allowed by the back-end server. To enable this, you can use the parameter Max-Forwards.

Assume a configuration as below.


<api xmlns="http://ws.apache.org/ns/synapse" name="CustomerAPI" context="/customer">
   <resource methods="DELETE POST PUT OPTIONS" url-mapping="/*">
      <inSequence>
         <send>
            <endpoint>
               <address uri="http://localhost:8280/proxyapi"></address>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send></send>
      </outSequence>
   </resource>
</api>

<api xmlns="http://ws.apache.org/ns/synapse" name="ProxyAPI" context="/proxyapi">
   <resource methods="PUT OPTIONS" url-mapping="/*">
      <inSequence>
         <send>
            <endpoint>
               <address uri="http://localhost:10763/jaxrs_basic_44/services/customers"></address>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send></send>
      </outSequence>
   </resource>
</api>


To retrieve the methods of the first API, you can specify the MAX-Forwards parameter as below.

$ curl -v -X OPTIONS http://localhost:8280/customer/customerservice -H "Max-Forwards: 0"

It would return the methods available of the first API which is CustomerAPI

* About to connect() to localhost port 8281 (#0)
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8281 (#0)
> OPTIONS /customer/customerservice HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8280
> Accept: */*
> Max-Forwards: 0
>
< HTTP/1.1 200 OK
< Max-Forwards: 0
< Host: localhost:8280
< Allow: POST, DELETE, PUT
< Content-Type: application/x-www-form-urlencoded; charset=UTF-8
< Accept: */*
< Date: Fri, 25 Apr 2014 12:17:02 GMT
< Server: WSO2-PassThrough-HTTP
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact

If you need to retrieve the methods of the second API, which is ProxyAPI, you need to give the command with Max-Forwards parameter set to 1. Then, it would return the methods allowed by that API only.

$ curl -v -X OPTIONS http://localhost:8280/customer/customerservice -H "Max-Forwards: 1"

The result would be as follows. It returns the available methods of the second API.

* About to connect() to localhost port 8281 (#0)
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8281 (#0)
< OPTIONS /customer/customerservice HTTP/1.1
< User-Agent: curl/7.29.0
< Host: localhost:8280
< Accept: */*
< Max-Forwards: 1
<
> HTTP/1.1 200 OK
> Max-Forwards: 0
> Host: localhost:8280
> Allow: PUT
> Content-Type: application/x-www-form-urlencoded; charset=UTF-8
> Accept: */*
> Date: Fri, 25 Apr 2014 18:20:16 GMT
> Server: WSO2-PassThrough-HTTP
> Transfer-Encoding: chunked
>
* Connection #0 to host localhost left intact


If you need the HTTP methods of the actual back-end server, you need to call the first API using a command as shown below

curl -v -X OPTIONS http://localhost:8280/customer/customerservice -H "Max-Forwards: 2"

It would give the result as below with all the HTTP methods allowed by the back-end.

* About to connect() to localhost port 8281 (#0)
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8281 (#0)
< OPTIONS /customer/customerservice HTTP/1.1
< User-Agent: curl/7.29.0
< Host: localhost:8281
< Accept: */*
< Max-Forwards: 2
<
> HTTP/1.1 200 OK
> Allow: POST,GET,DELETE,PUT,OPTIONS,HEAD
> Content-Type: application/octet-stream
> Date: Fri, 25 Apr 2014 18:20:13 GMT
> Server: WSO2-PassThrough-HTTP
> Transfer-Encoding: chunked
>
* Connection #0 to host localhost left intact