Amsterdam: Exposing REST APIs

Amsterdam: Exposing REST APIs

Hi everyone,

Some months ago we added a new feature to Consume REST APIs that was the first piece for the new integration capabilities of the platform.
Now we deliver the second piece, Expose REST APIs!

This way the Platform provides a RESTful way to easily share services from your Platform to other components.

Creating a service is very fast, just like designing any other action in OutSystems.

Create a REST API, Add some methods and logic and publish.

Your service will be immediately available in the location displayed in the URL property of the service.

Making your API secure
In RESTful APIs one of the most important security features is to have all requests made via HTTPS. So the platform by default sets the HTTP Security of your services to require SSL.
Turning it off is not recommended, even if the reason is "my development server doesn't have a valid certificate", since you will need it in production later. So take a little time and ensure your server is configured for HTTPS.


Another important step to securing your APIs is Authentication. We provide two options: "Basic" and "Custom". In both cases an "OnAuthentication" callback is created for Authentication purposes.

Basic mode requires HTTP Basic Authentication to be used and already provides the developer with the Username and Password sent by the user. If the User Provider is the "Users", then a call to the Login method is also added automatically.

In Custom mode no automatic logic is created, which allows the developer to decide where to get the credentials and what logic to perform. Access to request information can be done using the methods from HTTPRequestHandler extension (from System Components)

But now comes the hard part... you have to explain to others how to use your API!
Don't worry, accessing the root url of your service automatically displays the necessary documentation for the service. (This default behavior can be disabled in the service properties).

E.g. accessing my server via https://myserver/DirectoryService/rest/Contacts/ shows my service documentation:

Here is a video highlighting the first steps to use this feature.
The video also includes the improvements made to the Monitoring and Analytics components of the Platform regarding Integrations - no longer being "Web Service" and "Web Reference" specific - continuing to progress our ability to integrate with anything.

Note: the video was recorded with a Beta version, so some parts (like the documentation) are not 100% accurate.

To know more about exposing data using REST, please refer to the reference help.

What's next?
We have been getting a lot of feedback from this feature and we already have some improvements being prepared:
  • Capability to have more control over the generated URL's (input in the path, same URL for multiple HTTP methods)
  • Capability to set inputs/outputs to Record/ RecordList types
  • Improved detailed logging, similar to the one the feature "Consume REST" already has.

These are the main 3 points, not an extensive list (your input is not forgotten!).
We are always here to receive feedback and new ideas. Feel free to send us yours.

João Rosado

A very happy customer here.
My biggest question is at the moment:
Is there a way to toggle webservices on/off via ServiceCenter?


Glad you are liking it.
The answer to the "toggling" question is no, but I would like to understand the need.
Can you explain your toggle on/off use case?

João Rosado
The need is simple.

We have developed a lot of webservcies, yet some of them are not allowed to use publicly.
(they are created, but put back on the backlog)
thus we would like to toggle them off.
Or even better, some test-webservices which only are used for some testing when needed.

Of course this can be done with site-properties but that creates a ton of extra manual maintenance.

And perhaps in the future we can distribute the load on servers without the need of altering espaces.

my client is upgrading to Amsterdam and I noticed something... the Rest API I just created doesn't show up in Service Center in the Integrations tab for the eSpace where the API was created.

I only have Exposed SOAP, Consumed SOAP and Consumed REST... there should be an Exposed REST list.

Platform Version
Hi João,

Yes that is true, It's still missing on the current version.
It will be added in a couple revisions (still don't have a date for that).

João Rosado

1 Will there a way to customise the REST documentation theme?
2 Does the REST documentation work with
under the hood its using swagger, so it should work right? 

EDIT: it will works! hopefully outsystems dont break this!
You can access the swagger json defination file via https://<SERVER>/<eSpace>/rest/<API_Name>/swagger.json
Hey! I like your post. :)
By the way Robert, regarding the codegen.

We tested it and worked OK most of the times but most languages had issues implementing the Binary types
Also some issues with the Date type in C#.

The swagger spec regarding the Binaries is still very poor and both the documentation and codegen suffers with it.

The Date had issues when we tested the C# codegen, because it just assumed a C# type named Date....
Maybe they fixed it in the meanwhile.

João Rosado
João Rosado wrote:
By the way Robert, regarding the codegen.

We tested it and worked OK most of the times but most languages had issues implementing the Binary types
Also some issues with the Date type in C#.

The swagger spec regarding the Binaries is still very poor and both the documentation and codegen suffers with it.

The Date had issues when we tested the C# codegen, because it just assumed a C# type named Date....
Maybe they fixed it in the meanwhile.

João Rosado
 Thanks for the heads up!

BTW: I noticed there are some issues with the output of outsystems swagger.json , try importing outsystem's swagger json content into this swagger editor you get the following error 
Swagger Error

Data does not match any schemas from 'oneOf'

This is a very good feature, very straightforward and easy to create services now!

However I have some points:

1. The casing of the objects returned. In case of error, this is what I get: {Errors:[...], StatusCode}. But in Java world, as well as in Javascript, the casing is camel, and Java JSON parsers are case sensitive (at least Gson is). So you have to do unnatural casing of Java object for it to be parsed from this JSON, naming private fields in pascal casing. As for C#, I believe it should parse it regardless of the case, or at least any C# developer should be expecting camel casing in JSON received. So I think it would be much better if OutSystems used standard camel casing for JSON as well. It can even "fix" casing of the structures returned, so that you can name fields pascal casing in OS, but get camel casing in JSON.

2. Now REST services support JSON bodies, but they don't support url-encoded bodies (that was the only way supported before). Would be great if it supported both (based on Content-type), to simplify migration.
Bom dia a todos,
estou recedebdo erro 403, e não consigo resolver, como faço para corrigir este erro?
obrigado e desculpe pelo idioma.
Ola Agno,

O erro 403 é provavel que seja por causa do Http Security estar SSL e estares a chamar a api com http:// em vez de https://
Como expliquei no post inicial essa é o modo recomendado, para garantir a segurança da api. Portanto recomendo ter o servidor configurado para aceitar pedidos de https e fazer as chamadas dessa forma.
Se não for mesmo possivel é alterar o Http Security para none ....

(estou a assumir que é esse o problema, a resposta para alem do codigo de erro deve ter mais informacao com a mensagem que o causou)

Now in english:
The 403 is probably because the Http Security is set to SSL and you are calling the api with http:// instead of https://
As I explained in my initial post that is the recommended mode, to ensure the security of the api. So I recommend for the server to be configured to allow https requests and perform the calls that way.
If it really isn't possible, then as alterantive change Http Security to none ....

(I'm assuming that that is the issue, the response together with the error code should have more information with the actual error message that caused it)

João Rosado
Bom dia,

Obrigado João, tudo certo aqui.
I currently have two problems with the expose REST API:
1) it seems I can't debug exposed REST API methods (i.e. the debugger never hits the breakpoints I set), and;
2) the documentation does not show output parameters that are in the header (I have a result code in the header, and the result data in the body, but only the body shows in the documentation)

Possibly also a 3rd problem:
3) When I select "Open Documentation", I get an error: {"Errors":["HTTPS connection required."],"StatusCode":403}

This seems related to the information opening on http, while the HTTP Security is set to SSL.
Hi Killian,

1) Answered here.
2) Will look into it.
3) That means Service Studio was not able to login you via https. So it assumes the server doesn't have it configured at all. That value is cached for some time. You can try to force it to check for https availability by cleaning up the preferences in the Edit menu.

João Rosado
Kilian, to debug an exposed Web service you can use postman ( Note: Make sure you use postman on the same machine where you have service studio opened in debug mode.
hi robert,

i have created 1 rest api with post method having input parameter as binary data, when i called this api and send the binary data in it.. m not able to convert that binary data into plain text even by using binarytotext method.
plz help

Apart from this not belonging in this thread, what do you mean by "not being able to convert [it]"? What happens?

exposing REST API is great but is there any plans to add throttling out of the box?

Hi Steve,

Throttling is actually a use case that is best handled being done custom using extensibility (this in particular on the OnAuthentication callback) than being a out of the box feature.
I did a reseach on this topic recently and found that the amount of necessary configuration options make it hard to have a good out of the box solution. For example how do you want to group the counts: total count, by ip, by x-forward-for, api key, security token, ...

Here are some of my findings regarding it:
  • The best way to do it is at a load balancer or proxy level, actually removing the load from your frontend servers and not having to do anything at the api level
  • There is no perfect solution that cover all cases.
  • Most solutions that you will find on the internet are not prepared to work behing proxies, are susceptible to memory leak attacks, depend on session (that does not exist in REST) or have readlly bad threadsafe locking patterns.

João Rosado
Hi João,

thank you for your input, I agree 100%

In our case, before we expose any API to other developers I wanted some level of limiting.
Initially we're just going to log the API key use over a rolling 24hr and 60s peak. If defined count is exceeded, flag error log and return error code to the offending consumer.

I looked at some time ago. Its a 3rd party API traffic tool that looked prity good. Has anyone used it before?


Hi Joao,

I created this idea: about finding an easy way to refresh the methods of a consumed REST API (something like the "Refresh" option that exists for the SOAP services) and I was wondering if there is already a way to do this.

Have there been any new developments regarding this in Outsystems 10?
Not that I've seen, but then again, with the focus on the revolutionary native offline apps, a lot of minor changes have gone without attention.

There will be some improvements, yes.
The major one will be that all structure attibutes will have a "Name in JSON" property, allowing you to customize how names of attributes are serialized/deserialized.(See use case here).

João Rosado
Joao that's perfect! Will the swagger documentation model display the actual structure name or the name or the customised attribute name? (can we also change the node name?)
It will show the name of how it will be serialized.

By the way, who noticed on the presentation the 2 new icons on the left side tool bar when inside actions?
And who can guess what they are for? :P

Edit: what you mean by the node name? in json only the attribute names get serialized. The structure names do not appear in the payload.
I can't say I noticed them, amongst all the new and exciting things :). I'll check tomorrow with Matthias :)