When it comes to REST APIs we know how to get the best of Mule. We make a RAML that is API metadata description, then kick off Mule automation that will create API Kit Router configuration and flows. Then we only need to add business logic to auto generated flows and API is ready. Truly ready? Wait a moment.
Let’s focus on capabilities of API Kit Router. Developers that I meet are not always aware of all of them or just they think API Kit Router is a magical tool they should rather leave untouched. It needs to be touched always but when making proper use of it you will not get your hands very dirty with coding.
There are 2 main functions that we have in API Kit Router
Routing.
It will route requests to auto-generated flows based on path, request type (get, post, etc) and payload content-type. You have out of the box error handling here – a bunch of 4* error responses relevant to the nature of error. It will handle wrong request types, paths and request body.
When it comes to routing there is not much that can be enhanced. Automation that creates flows for all RAML paths and methods is using certain naming conventions and when you do not change anything it always works as expected.
The only thing that you need to work out yourself is how to approach any fixes you make in RAML and want to apply on existing flows when logic is already there. I usually make automated flows on a clean project aside and just copy-paste flow names into my WIP app. It is extremely easy to make typo and then API Kit Router messages can be confusing.
Request body validation.
When you put a schema on your request body (in RAML) it will use it to validate payload. Usually REST endpoints accept JSON and you will apply JSON schema but you can also impose XML schema. Then you can have a REST endpoint with XML schema validation. Whichever format you use, when constraints in schema are present, the API Kit Router will apply them on incoming payload and will return relevant 4* response message when payload is invalid even before entering any flow.
Validation error messages that come out of the box are too generic. 400 and “Bad request” is not a message that I want to see when consuming a webservice. This is how I fine-tune validation errors.
Standard error message is set to static “Bad request” in a “Set Payload” component. To add details I use exception object and get cause from it. All quotes (“) must be escaped to prevent breaking JSON contract.
It is a routine change that I do in error handling. When a bad request happens the client will receive a meaningful response. It speeds up client integrations and allows you to focus on project work rather than supporting your partners.
Another thing I always do is internal error handling in all API flows. If there is no error handling client will get a happy response (depending on your RAML some 2xx http status code) and a nasty Java exception stack trace when there is an exception in your flow. Fatal flaw in design and I see it too many times.
In case of internal errors (or server side errors) I rather want to put a veil on what happened internally and give clear instruction to the client – i.e. what actions can be taken on client end. And certainly some 5xx status code should be returned.
Let me simplify my example to very basic scheme with a catch exception strategy with one catch condition just catching all exceptions.
The first 3 elements are aligned to corporate error handling pattern: make standard error bean, print to log and push to error queue. For sure RBLogger is worth another post and I will not cover it now. The last 2 are responsible for setting a response to client.
The last step is to set a meaningful response message to the client.
Let me concentrate on the error message. Whenever I set something that is returned to the client I try to jump in client shoes for a moment.
The first thing is to assure client that the problem lies on server (API) side. The second is to prevent unnecessary communication that will only take away your time. We have the error logged in our issue tracking system and there is no need to add noise from all dependent clients to that. If you have any status page where you let your partners see your incidents you can include it here.
Summary
API Kit Router is a very stable and mature mechanism that speeds up API design and build. It moves API design from execution code to RAML metalanguage and makes it very easy to mockup and prototype APIs. Although validation and error handling are out-of-the box features they need a few enhancements that should always be on your checklist.