Error Handling in APIKit-based Projects

[This article was originally written by Eugene Berman.] 

If you look at the W3C document listing HTTP status codes, you may notice that only a small portion of all possible codes represents the happy path – i.e. 2xx codes. Most other codes are there to let client know that something went wrong with the request and the expected response cannot be returned. When building an APIKit-based application, developers must properly handle error conditions and set status codes accordingly. As always with Mule, there are many ways to achieve that. Let’s look at some of them.

Our use case is a very simple ACME Company API which returns a product information based on a particular product ID. In other words,

GET /products/{id}

Our RAML is as follows:

#%RAML 0.8
---
title: Acme REST API
version: v0.1
baseUri: http://localhost:8081/acme/{version}
          
/products/{id}:
    displayName: Product    
    get:
      description: Get Product by ID
      responses:
        200:
          body:
            text/plain:

When we create a new APIKit project in Studio and add a RAML file, it generates flows for each RESTful call. In our case, it will produce one flow which handles our request:

<flow name="get:/products/{id}:acme-config" doc:name="get:/products/{id}:acme-config">
    <set-payload value="#[NullPayload.getInstance()]" doc:name="Set Payload"/>
</flow>

We can now replace the default content of this flow with a business logic that queries the database and returns product information:

<flow name="get:/products/{id}:acme-config" doc:name="get:/products/{id}:acme-config">
    <jdbc-ee:outbound-endpoint exchange-pattern="request-response" queryKey="GetProductByID" queryTimeout="-1" doc:name="Database">
        <jdbc-ee:query key="GetProductByID" value="SELECT * FROM Products WHERE ID=#[flowVars['id']]"/>
    </jdbc-ee:outbound-endpoint>
    <!-- add transformation logic here -->
</flow>

But what if our query returns no results? From the JDBC transport perspective, this is not an error condition – the returned payload will simply be an empty list. In this case, our API call will return an empty response, with the HTTP status code 200 – something the client would expect. Or, if our transformation logic expects some data from the database, it may fail, throwing an exception – again, not the desired behavior. What we really need is to return status 404 and potentially some object containing more details. All we need is to add a <choice> message processor, e.g.:

<choice>
	<when expression="#[payload.size != 0]">
		<!-- Add processing logic here -->
	</when>
	<otherwise>
		<set-property propertyName="http.status" value="404"/>
		<set-payload value="Quoth the server, 404"/>
	</otherwise>
</choice>

How about any other scenarios where something else may go wrong? Wouldn’t it be great if we had an exception strategy which can automatically map exceptions to response codes?

Let’s look at our generated code again. There’s a new global element called apikit:mapping-exception-strategy:

    <apikit:mapping-exception-strategy name="acme-apiKitGlobalExceptionMapping">
        <apikit:mapping statusCode="404">
            <apikit:exception value="org.mule.module.apikit.exception.NotFoundException" />
            <set-property propertyName="Content-Type" value="application/json" />
            <set-payload value="{ "message": "Resource not found" }" />
        </apikit:mapping>
        <apikit:mapping statusCode="405">
            <apikit:exception value="org.mule.module.apikit.exception.MethodNotAllowedException" />
            <set-property propertyName="Content-Type" value="application/json" />
            <set-payload value="{ "message": "Method not allowed" }" />
        </apikit:mapping>
        <apikit:mapping statusCode="415">
            <apikit:exception value="org.mule.module.apikit.exception.UnsupportedMediaTypeException" />
            <set-property propertyName="Content-Type" value="application/json" />
            <set-payload value="{ "message": "Unsupported media type" }" />
        </apikit:mapping>
        <apikit:mapping statusCode="406">
            <apikit:exception value="org.mule.module.apikit.exception.NotAcceptableException" />
            <set-property propertyName="Content-Type" value="application/json" />
            <set-payload value="{ "message": "Not acceptable" }" />
        </apikit:mapping>
        <apikit:mapping statusCode="400">
            <apikit:exception value="org.mule.module.apikit.exception.BadRequestException" />
            <set-property propertyName="Content-Type" value="application/json" />
            <set-payload value="{ "message": "Bad request" }" />
        </apikit:mapping>
    </apikit:mapping-exception-strategy>

It allows mapping exception types to status codes, content types, error messages and anything else you may want to return as a part of your error response. You can add as many mappings as you need, however, you will have to either know all types of exceptions at the design time (which is not always possible) or throw a specific exception using Java or scripting component, e.g.:

<scripting:component>
    <scripting:script engine="groovy">
        <![CDATA[
	    throw new org.mule.module.apikit.exception.NotFoundException("Product ID does not exist!"); 
	]]>
    </scripting:script>
</scripting:component>

In reality, a combined approach should be used. Use as much logic as possible to gracefully handle some error conditions, use mapping exception strategy to intercept and map other errors.

Now you can finish your ACME API, connect it to a database of your choice and send the request for a product that does not exist in the database.

Quoth the server, 404…