TIP: Error handling in WSO2 ESB APIs when the requested API resource does not match with the given URL template or pattern

When you send a HTTP request to an API in WSO2 ESB, if the requested API resource URL does not comply with the API resource definition, ESB returns HTTP 202 accepted response to the user. Due to  this behavior, the client is unable to distinguish if they have made an error. We can use the following procedure to return a fault to the client in case of non-matching API resource is requested by client.

Step 1:

Suppose, we have an API similar to the following. Note that, the target web service is a JAXRS web application (jaxrs_basic) which is included in WSO2 Application Server by default.

<api xmlns="http://ws.apache.org/ns/synapse" name="jaxrs" context="/jaxrs">
   <resource methods="GET" uri-template="/customers/{id}">
               <address uri="http://localhost:9764/jaxrs_basic/services/customers/customerservice"/>

Step 2:

Send the following HTTP GET request to the above API. (You can use a soapUI web testcase as instructed in one of my previous blog posts).

GET http://localhost:8280/jaxrs/customers-wrong/123

Step 3:

You will get HTTP 202 accepted response because the request URL does not match with the resource url-template defined in the API.

Step 4:

Now, add the following fault handling sequence in ESB. Once the API receives a request which does not match with any of the resource url patterns/templates, this sequence will be invoked. Make sure to name the sequence as _resource_mismatch_handler_

 <sequence xmlns="http://ws.apache.org/ns/synapse" name="_resource_mismatch_handler_">
         <tp:fault xmlns:tp="http://test.com">
            <tp:type>Status report</tp:type>
            <tp:message>Not Found</tp:message>
            <tp:description>The requested resource (/$1) is not available.</tp:description>
         <arg xmlns:ns="http://org.apache.synapse/xsd" expression="$axis2:REST_URL_POSTFIX"/>
   <property name="RESPONSE" value="true" scope="default"/>
   <property name="NO_ENTITY_BODY" action="remove" scope="axis2"/>
   <property name="HTTP_SC" value="404" scope="axis2"/>
   <header name="To" action="remove"/>

Step 5:

Send the above HTTP GET request again. This time, you will get a proper error as shown below.

HTTP/1.1 404 Not Found
Content-Type: application/xml; charset=UTF-8
Accept-Encoding: gzip,deflate
Date: Fri, 16 Nov 2012 06:06:51 GMT
Server: Synapse-HttpComponents-NIO
Transfer-Encoding: chunked 


Does this work with REST APIs in wso2 ESB 4.8.0?
Charitha said…
Though I did not test this with ESB-4.8.X, this should work
Unknown said…
Hi Charitha,
I have created an api in wso2 esb 4.8.1. I am redirecting it to a fault sequence I created in case of any faults.
During fault cases it goes into the sequence but when I try to send the response back from the fault sequence to the client it is unable to send it and instead goes back to the outsequence.
Below is the fault sequence code:

"status": "Fail","code": "$1","reason": "$2"}

Charitha said…
Can you please post this question in wso2 opensource public forum? I have not been working with WSO2 middleware stack for more than 2 years hence I'm not sure about their new implementations.

Popular posts from this blog

Common mistakes to avoid in WSO2 ESB - 1 - "org.apache.axis2.AxisFault: The system cannot infer the transport information from the URL"

Working with HTTP multipart requests in soapUI

How to configure soapUI to send HTTP chunked encoded requests