Integrating with REST APIs

Integrating with REST APIs

Update: This functionality (both exposing and consuming REST services) is now native in the OutSystems Platform, rendering this discussion outdated.

At Support we have been getting requests from people asking about how to integrate with REST API, or RESTful webservices. We usually answer that the OutSystems Platform does not natively support consuming REST. This doesn't mean that you can't integrate with a REST API, it just means that you don't have it as easy as when using a SOAP web service.
When people ask us this most of the times it seems that they are not really sure what a REST API is and are just asking us if there is a simple way to integrate with this new strange thing.

What exactly is a REST API?

Basically a REST API is a set of web (HTTP) end-points which return some data or perform some operation. The data returned is usually either in XML or JSON for easy processing by Javascript. The aim of this kind of interface is to do away with all the bureaucracy involved in calling a SOAP web service.

Why doesn't the OutSystems Platform support this?

The OutSystems Platform doesn't support importing these APIs like you can import a SOAP web service. But it doesn't mean that you can't consume REST APIs with the OutSystems Platform. Unfortunately, it does mean that you will have to do a lot of work on your own.

The main difficulty I have found with REST APIs is the lack of a description language for them. Well, it's actually not that there isn't any description language for REST APIs (there's WADL and a few more of those available), it's that most of the people who define REST APIs don't offer such descriptions of their APIs (take Jira and Google Books as an example).

Edit: As of the OutSystems Platform 9, the OutSystems Platform DOES support consuming REST APIs. 

What can I do?

Well, that depends on what you're given, doesn't it?
There are basically two paths: implementing the integration in Service Studio or in Integration Studio. In either solution you'll have to create the OutSystems structures you need to represent your data.

Implementing it in Service Studio

Like I said, REST APIs are basically defined by some web requests (the "methods") and the data that they return / need, which are usually JSON or XML. So one thing you can do is precisely this: encapsulate the requests and data processing in a Service Studio Action.
You can use RichMail's HTTPGet to do GET's and HTTPRequestHandler's GetRequest_Submit to perform POST's. Problem with these APIs is that they're limited and don't support sending some extra parameters like headers and cookies. But in most cases they should be enough.

In the cases where those actions are not enough, you may want to take a look into the ardoHTTP component which provides a more complete API for performing all kinds of HTTP requests.
To process the returned data you can use a component for processing JSON data (ardoJSON, WebServiceEngine) or for processing XML data (XML Records) into OutSystems structures.

One part of processing the JSON data is creating the corresponding OutSystems structures to hold that data. This process can be long and tedious. I have started implementation of a component which aims to help with this, RESTWebServices. At the moment, this component allows you to provide a JSON example and it will automatically generate a WSDL which, when imported into Service Studio, will create the structures necessary to process the provided JSON request.
Implementing it in Integration Studio

If the supplier for your API happens to have a .NET or Java library available to consume his API, then you might want to consume the API in an extension. If you also have a WADL description of the API, you may want to use automatic code generators and build the library yourself.
In any case you'll need to convert the data between what's returned by the REST API and the OutSystems Application, which would involve creating the structures to represent the data and filling them up. Both .NET and JAVA have decent support for XML processing, and there are some good libraries to easily and quickly process JSON data in both .NET (JSON.NET) and Java (jackson).

Unfortunately OutSystems structures are not the most convenient receptable for the most convenient JSON processing APIs to use and you'll have to perform a lot of coding by hand to fill them up.

Implementing in Service Studio [Version 9 and above]

As of version 9 of the OutSystems Platform it is now possible to consume REST APIs as if they were web references. Since there usually aren't any description languages, the approach in the OutSystems Platform is much like the one described for ardoJSON + ardoHTTP + RestWebServices. You provide an example, tell the platform what's the endpoint and the OutSystems Platform will generate the required structures, HTTP calls and JSON processing under the hood.

Check out the help page on consuming REST APIs for more details.

Don't keep it to yourself, SHARE!

Have you implemented an integration with a REST API? Don't keep it to yourself. Share it in the Forge. Tag your component with REST so that it is easily searchable.

More coming up!

I'm working (on my free time, so it may take a while) on an full solution to help consuming REST APIs in Service Studio and will keep this thread updated on that regard. 
ardoJSON (my JSON processing extension) is the first piece on this solution.
ardoHTTP is an extension for giving you control over how the HTTP requests are made.
RESTWebServices is a component which allows you to semi-automatically generate the structures which are necessary to process JSON data in ardoJSON.

Discuss your experience

If there is something you'd like to add to this topic, feel free to reply to this thread. Your experience in integrating with REST APIs is more than welcome.
Nie to see someone working on this :) Ive managed to integrate SkyDrive with REST API in service studio. Made a file picker which does its job.
I have to say it was tricky to get it to work at first as there was no info on how to do this with service studio. It is most likely not the cleanest solution but it does its job. For now it just has to work. Was planning on improving it at a later time.
Looking forward to your work on this :)
How did you authenticate with the API?
I've done tons of REST API integrations with the OutSystems Platform, and each one was different. Why? because each API was so different! There really is no "one size fits all" answer to this question.


In Authentication, like so many things in the REST world, each case is a different case.

Google Drive API likely uses OAuth as an authorization schema, or something of the sort (I couldn't find the REST API description for hte Google Drive API, but I did find the one for Google Books, which uses OAUTH in some parts).

Other systems have different authentication schemas. Some use keys passed as parameters, others use the underlying HTTP Authentication.

From what I saw in your other post (and your support request) you are trying to use HTTP Authentication. Unfortunately the HttpWebRequest class used by RichMail's HttpGet action has a "weird" behavior when it comes to authorized requests. By default it will only send an authorization if specifically asked for it.

My suggestion, if your server is not responding well to this behavior, is for you to create your own HTTPGet which supports preemptive authentication on the request.
Today I have released a component to be used in conjunction with ardoJSON which helps with the task of taking a JSON and creating the necessary OutSystems structures to support it.

You can check the RESTWebServices component here.

Later on I will update the original post with how this fits into integrating with REST APIs in the OutSystems Platform.
A new component to aid you in integrating with REST APIs was born.

ardoHTTP gives you unprecedented control your HTTP requests, which is invaluable in integrating with REST APIs.

I will soon update the original post to include information about how these two components (RESTWebServices and ardoHTTP) fit into integrating with these APIs in the OutSystems Platform.
Ricardo Silva wrote:
Today I have released a component to be used in conjunction with ardoJSON which helps with the task of taking a JSON and creating the necessary OutSystems structures to support it.

You can check the RESTWebServices component here.

Later on I will update the original post with how this fits into integrating with REST APIs in the OutSystems Platform.
Rcardo, This component is extremely useful! It can save a developer alot of time!
Keep up the good work and thanks for mentioning WebServiceEngine :)
Hi all,

I've just released a component to ease the integration with Google API's oAuth using Ricardo's ardoHTTP and ardoJSON. Thanks for the help Ricardo!

The new component is here


How do I perform preemptive auth using ardoHTTP?
I am on version

You just set the credentials on the request. The default mode for HTTP Authentication is preemptive.
You mean, I just set the Username and Password parameters of the HTTPGet/HTTPPost actions of ardo?
Does not work.

Here is the scenario. I am hitting a service at a http location "A"  (does not require auth). "A" gives me another https location "B" which requires auth. 

I am using HTTPGet to reach A and HTTPGet.Response to reach B. 
In HTTPPost, I am setting the username/password combination that I have.

Please move this discussion to a discussion in ardoHTTP component. And provide an example eSpace illustrating that the http authorization request is not being correctly sent.

Have you integrated with SAP Netweaver Gateway? 

I have updated the original post to reflect the fact that the OutSystems Platform 9 now already incorporates mechanisms to more easily consume REST APIs :)

I read all the previous posts, but I still have a simple doubt:

It's possible to create a REST Service in OutSystems?
(expose the webservice to be consumed)


Not yet, but .... soon :)