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,
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:
We can now replace the default content of this flow with a business logic that queries the database and returns product information:
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.:
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:
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.:
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.
MuleSoft provides the most widely used integration platform for connecting any application, data source or API, whether in the cloud or on-premises. With Anypoint Platform®, MuleSoft delivers a complete integration experience built on proven open source technology, eliminating the pain and cost of point-to-point integration. Anypoint Platform includes CloudHub™ iPaaS, Mule ESB™, and a unified solution for API management™, design and publishing.