Unusual Scenarios for HTTP Methods in REST

When sending REST messages to an API , you typically use POST or PUT to send a message and GET to request a message. However, there are some unusual scenarios you might want to support, which are described in the following sections:

Using POST with No Body

Typically, POST is used to send a message that has data enclosed as a payload inside an HTML body. However, you can also use POST without a payload. WSO2 Enterprise Integrator (WSO2 EI) treats it as a normal message and forwards it to the endpoint without any extra configuration.  

The following diagram depicts a scenario where a REST client communicates with a REST service using WSO2 EI. Apache Tcpmon is used solely for monitoring the communication between WSO2 EI and the back-end service and has no impact on the messages passed between WSO2 EI and back-end service. For this particular scenario, the cURL client is used as the REST client, and the basic JAX-RS sample is used as the back-end REST service.

   To implement this scenario:

1. Configure and deploy the JAX-RS Basics sample by following the instructions for building and running the sample on the JAX-RS Basics page.

2. Start WSO2 EI  and change the configuration as follows:

   <definitions xmlns="http://ws.apache.org/ns/synapse">
      <sequence name="fault">
         <log level="full">
            <property name="MESSAGE" value="Executing default sequence"/>
            <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
            <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
         </log>
         <drop/>
      </sequence>
      <sequence name="main">
         <log/>
         <drop/>
      </sequence>
      <api name="testAPI" context="/customerservice">
         <resource methods="POST" url-mapping="/customers">
            <inSequence>
               <send>
                  <endpoint>
                     <address uri="http://localhost:8282/jaxrs_basic/services/customers/customerservice"/>
                  </endpoint>
               </send>
            </inSequence>
            <outSequence>
               <send/>
            </outSequence>
         </resource>
      </api>
   </definitions>

   In this proxy configuration, testAPI intercepts messages that are sent to the relative URL /customerservice/customers and sends them to the relevant endpoint by appending the url-mapping of the resource tag to the end of the endpoint URL.

3. Start tcpmon and make it listen to port 8282 of your local machine. It is also important to set the target host name and the port as required. In this case, the target port needs to be set to 8280 (i.e. the port where the backend service is running).
   We will now test the connection by sending a POST message that includes a payload inside an HTML body.
   

4. Go to the terminal and issue the following command:
   curl -v -H "Content-Type: application/xml" -d "<Customer><id>123</id><name>John</name></Customer>" http://localhost:8280/customerservice/customers
   

5. The following reply message appears in the console:

   <Customer>
      <id>132</id>
      <name>John</name>
   </Customer>

    

6. Now send the same POST message but without the enclosed data as follows:
   curl -v -H "Content-Type: application/xml" -d "" http://localhost:8280/customerservice/customer

   You would need to configure the backend service to handle such requests, if not the WSO2 EI will throw exceptions.

          The tcpmon output shows the same REST request that was sent by the client, demonstrating that WSO2 EI handled the POST message regardless of whether it included a payload. 

Using POST with Query Parameters

Sending a POST message with query parameters is an unusual scenario, but the ESB supports it with no additional configuration. WSO2 EI forwards the message like any other POST message and includes the query parameters.

To test this scenario, use the same setup as above, but instead of removing the data part from the request, add some query parameters to the URL as follows:

curl -v -H "Content-Type: text/xml" -d "<Customer><id>123</id><name>John</name></Customer>" 'http://localhost:8280/customerservice/customers?param1=value1&param2=value2'

When you execute this command, you can see the following output in tcpmon:

POST /jaxrs_basic/services/customers/customerservice/customers?param1=value1&param2=value2 HTTP/1.1
Content-Type: application/xml; charset=UTF-8
Accept: */*
Transfer-Encoding: chunked
Host: 127.0.0.1:8282
Connection: Keep-Alive
 
32
<Customer><id>123</id><name>John</name></Customer>
0

As you can see, the query parameters are present in the REST request, demonstrating that WSO2 EI sent them along with the message. You could write resource methods to support this type of a request. In this example, the resource method accessed by this request simply ignores the parameters.

Using GET with a Body

Typically, a GET request does not contain a body, and WSO2 ESB does not support these types of requests. When it receives a GET request that contains a body, it drops the message body as it sends the message to the endpoint. YOu can test this scenario using the same setup as above, but this time the client command should look like this:

curl -v -H "Content-Type: text/xml" -d "<Customer><id>123</id><name>John</name></Customer>" 'http://localhost:8280/jaxrs_basic/services/customers/customerservice/customers/123' -X GET

The additional parameter -X replaces the original POST method with the specified method, which in this case is GET. This will cause the client to send a GET request with a message similar to a POST request. If you view the output in tcpmon, you will see that there is no message body in the request.