OutSystems Developer Cloud REST Integration — To Code or not to Code

An opinion on when to consume REST APIs using custom code in OutSystems Developer Cloud.

In April 2024, I published a connector library on OutSystems Developer Cloud Forge for the DeepL translation service API. Shortly after, a community member asked why I am using external logic functions leveraging the official DeepL .NET SDK instead of just consuming the REST API in a “normal” library.

I’d like to share my thoughts on when to use the built-in visual approach in ODC to consume a REST API and when it’s better to use a custom code approach with ODC External Logic functions.

If I need to create an integration with a REST API, then I ask myself the following two questions and if one of them is applicable, then I opt for a custom code integration via ODC External Logic.

Does the vendor provide a .NET SDK and explicitly recommends using the SDK instead of directly using the REST API?
For instance, both Microsoft and Amazon advise using their SDKs rather than directly accessing the REST APIs of their Azure and AWS services. In such cases, I would always create an ODC External Logic connector library that wraps the SDK functions, despite the slight increase in latency it causes.

Do I have specific requirements in terms of resilience / fault tolerance when integrating with the vendor’s REST API?
When using REST APIs, we cannot always assume that the service will work or respond in the way we expect it to. In general, we differentiate between permanent and temporary errors.

In the case of permanent errors, e.g. because we have not sent all the data required for processing and receive a 400 Bad Request status, we have no choice but to cancel our processing. There would also be no point in sending the same request a second time.

This is not the case with temporary errors, also known as transient errors. A classic here is a status 429 — Too many requests, which expresses that we have simply sent too many requests to the service in a certain period of time. However, the same request to the service a few seconds or minutes later would lead to successful processing.

For example, the DeepL .NET SDK includes Polly, a library that offers multiple resilience patterns to enhance the reliability of consuming REST APIs. I’m not saying that building these resilience patterns in OutSystems Developer Cloud is impossible. It is possible, but it would require a tremendous amount of time — more time than simply using the already built and tested SDK provided by the vendor. DeepL does not explicitly recommend using their SDK, but in response to the second question, I answered yes. Since resilience is already built into the existing .NET SDK and I know from experience that sometimes temporary errors occur with the DeepL API, I opted for a custom code external logic connector.

But what should I do if I need resilience and the provider doesn’t offer an SDK with built-in resilience?

If the vendor provides a proper and well-written OpenAPI specification, you can generate an SDK that includes resilience options using Microsoft Kiota. Kiota is a powerful toolkit for generating code from OpenAPI specifications, supporting not just C# but many other programming languages as well.

The downside is that you really need a good OpenAPI specification file. Many niche vendors often provide a very basic, sometimes entirely unusable OpenAPI file. In that case, you would either need to make amendments to the file before generating code with Kiota or build your own resilience patterns directly in ODC.