How to get an error message when a REST Component Binding receives a badly formatted JSON message in BusinessWorks and BusinessWorks Container Edition

By default REST Component Bindings exposing REST APIs can handle JSON messages with fields in any order and can be configured to filter silently unknown fields meanwhile in cases of badly formatted JSON messages or when mandatory fields are missing the BusinessWorks engine returns an HTTP status 400 with no explanations on why the message got rejected.
This article is to present a solution allowing to log error details and return them to the client application.

The problem

You have an API end point expecting a JSON message in a given format.

For example, using a basic petstore swagger file, downloaded from the swagger.io site, you can create a process exposing an API endpoint supporting two methods post and put.

Example of a process exposing an API endpoint supporting two methods post and put

Using swaggerUI you can check the format expected by the post method:

JSON message format expected by the post method of our example API

If you call the API with a JSON message where the ‘name’ and ‘photoUrls’ fields of the pet structure are missing, you get a bad request error message like below which is not helpful to understand the issue.

Error 400 Bad Request message received after sending a badly formatted JSON message

The solution

The solution is simply to select the ‘Start Job on Input Exception’ option available in the REST Component Binding configuration, to add a Catch all branch at the highest level of the process definition and to return error details from that branch.

Enabling the ‘Start Job on Input Exception’ option:

Setting the ‘Start Job on Input Exception’ option on the binding

Adding a Catch all branch at the highest level of the process definition:

Adding a Catch All at the highest level of the process definition

Returning details about the error:

Returning details about the error

Now if you call the API with a partial JSON message like before you get details about the error allowing to understand the source of the problem (in our example a ‘name’ field or object is missing in the structure).

Error details are now returned from our example process

Summary

A BusinessWorks development best practice is for REST Component binding to return error details when a badly formatted JSON messages is received, this can be done by using the ‘Start Job on Input Exception’ option and adding a Catch all branch at the highest level of the corresponding process definition.