API Error Handling

Good practices for API error respones

APIs must be designed for two scenarios: (see here)

• The Green Path - stands for SUCCES and responds the expected data (success profile).

• The Red Path - stand for failure and responds Information about the failure.

j.GPR.KeyValue.GET.RES and j.API.Error.RES

There are a couple of good practices for APIs and I wanted to mention a few of them here:

• Do use one profile for a successful response (http-20x) j.GPR.KeyValue.GET.RES

• Do use one profile for all non-success responses (not http-20x) j.API.Error.RES

Do use the same error profile in all end-points / services, and place it on a prominent place in your repository - it is shared!

There is only one j.API.Error.RES and this profile is the basis for your error pattern. However, you will see later that there is a second error profile called: j.API.Errors.RES (plural), which is used when we work with arrays.

• Use http-200 when you return a response body. Even if it is an empty Json, like { }, it is a Json and it is a non empty body -> 200.

• Use http-204 when you don't return any data - no body.

The API logic sub-process

The sub-process looks like this:

1. It implements the API end-point logic wrapped into the top-catch block,

   1. where the exception is handled and

   2. turned into an j.API.Error.Res

API Logic Pattern with exception handling

If we look into func.GetKeyValue() we will not find a try/catch block. Instead, when the business rules shape fails, we turn the failure (error) into a controlled exception and abort execution. The parent (top-level) catch will handle this exception!