Often developers reach out to us on how to handle HTTP status codes when consuming a REST API in OutSystems.

This topic is covered in the OutSystems documentation here and it's a good place to start to get some context.

Default behavior

By default the platform automatically raises an exception if the status code is outside of the 2xx range. I wasn't able to test what happens if the status code is on the 1xx or 3xx range.

When you call the API method you can trap the exception with an "AllExceptions" or let it bubble up to the generic exception handler. Something like this:

The end result looks something like this (you can try it out here)

This approach however has 2 downsides, it doesn't have any granularity on the type of exception and also it looses any details of the error that the API maybe passing to help the developer process the error.

An example would be, while consuming a REST service protected by oAuth, getting a 401 Unauthorized when a toke is expired would allow you to refresh the token and execute the request again.

Handling the exceptions

Getting the error details from the REST

Often I've seen developers "forgetting" to include the error response from the consumed REST API's in the OutSystems response.

For example, in this Google calendar API, the developer did not include the error structure:

This is often the case since most REST API's documentation have the error handling on a separate topic. So for example the GetEvent response documentation:

And here is the error documentation:

However there is nothing stopping us from including the error structure from the documentation into the response example in OutSystems, something like this:

This will create an extra structure for the REST API that will still be able to parse the response in the event of an error, allowing the developer to handle the error in a more granular way.

Generating REST exceptions

The Developer can then inspect the HTTP status code on the "OnAfterResponse" and decide what to do with it. Some choose to raise specific exceptions for each type of code (something like this)

Or create a generic REST exception that can be introspected for details (something like this):

Note that in the example above, the Developer choose to pass the response text into the Exception message. This will allow him to deserialize the exception message into the REST API error structure created on the previous step, introspect the error and act accordingly.

The 3rd Option

This option represents a "not so good practice" and it is only being mention because some REST API's choose to always return HTTP code 200 Success even if reporting an error in the details. If you want you can convert any REST API into always return HTTP 200. However the developer must be aware that introspecting the error structure from the API is a must to check for errors. This is why it is considered a bad practice.

This is accomplished by changing the status code in the "OnAfterResponse":

Use at your own risk!

Playing with the example

On the example provided you can choose the 3 options discussed.

Here is a video of the example from Jay Santos

Enjoy