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,
latest report
Learn why we are the Leaders in API management and iPaaS
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.
