Retrieving Data from a REST API 

(GET method) 
 
 
 

   

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 1 
  

Table of Contents 
Table of Contents 2 

Introduction 3 
Connect to an Environment 3 

Get to know the scenario 5 

Install the Contacts application 5 
Business Case Overview 5 

Define the REST API Method - GET 5 

List Contacts on the screen 13 

End Lab 20 

 

   

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 2 
  

Introduction 
In this lab, we are going to integrate with a REST Web Service to retrieve data from an external 
system. We are going to use the GET method to read information of the Contacts in the 
external system and then display that data in our application. 

Connect to an Environment 
When we open Service Studio for the first time, we will need to connect to an ​environment 
where the OutSystems platform server generates, optimizes, compiles, and deploys 
OutSystems applications. 

1) Open Service Studio and access the ​Connect to Environment d

​ ialog. This can be done 
in two ways. 

a) If you are not logged in to any environment, click on C

​ onnect to Environment​. 

b) If you are already logged in to an environment, select the ​Switch Environment... 

option from the Environment menu at the top. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 3 
  

2) Connect to your OutSystems personal environment. 

a) If you are using your Personal Environment, you can find its address in the 
OutSystems ​website​ and log in.  

b) Under the ​Platform​ tab and then under the P

​ ersonal Environment​ tab the 
environment address (or S
​ erver Address​) can be found.  

  

c) Back in Service Studio, use that Environment and login with your OutSystems 
community email (username) and password. 

   

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 4 
  

Get to know the scenario 

Install the Contacts application 

Open and publish the R
​ EST Contacts - GET.oap​ in your personal environment. The oap file can 
be found in the Resources folder.  

1) In the Applications, open the Environment menu and select ​Open Files…

2) In the Open dialog, change the File Type dropdown option to​ OutSystems Application 
Pack (*.oap)​ and then open the REST Contacts - GET.oap.  

3) Click Proceed when asked. 

4) Wait for the installation to complete and then proceed. 

Business Case Overview 

The REST Contacts application is a simple application, only containing a couple empty Screens, 
Preparation and some Screen Actions, also empty. These elements is where we’ll create the 
logic to get the Contacts and display the list on the screen.  

The quick start application is simply to speed up the setup part and start right away working 
with the external REST web service. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 5 
  

Define the REST API Method - GET 

In OutSystems, integration with REST Services can be straightforward. OutSystems helps us to 
generate all the methods and data structures needed to integrate with an external system. 

The GET request is known as a an idempotent and safe method as there are no changes in the 
resource when calling it and the results are always the same for identical requests. 

Before you consume any REST API it’s important to gather all the information you need from 
the REST API documentation. Information such as the expected structures and some examples 
maybe be really useful when consuming an external service. In this lab, the documentation for 
the external REST Web Service is available ​here​. 
In this section we will create the integration with the external REST Web Service. The data that is 
retrieved from this Web Service will later on be used and displayed on a Web Screen. 

1) Open the Contacts module 

a) In the Applications list, locate the R
​ EST Contacts​ Web application and open it. 

b) Open the ​RESTContacts m

​ odule 

2) Consume the GET method of the external REST Web Service. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 6 
  

a) Switch to the Logic tab and in the Integrations folder, right-click the REST 
integration element and select C
​ onsume REST API...​. This opens a window to 
configure the REST method that you want to consume. 

 
b) On the new window, click the A
​ dd Single Method​ button. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 7 
  

NOTE:​ The Add All Methods option allows to integrate with REST Web Services 
that provide a Swagger definition file. This speeds up the integration process a 
lot, however not all Web Services provide this. Regardless if Swagger is available 
or not, you can use the Single Method option. 

c) Set the ​Method URL t​ o 

https://foundation.outsystems.net/ContactsAPI/rest/v1/contacts/ 

d) Keep the ​HTTP Method​ to ​GET​. 

e) Switch to the ​Test t​ ab, then click the Test button 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 8 
  

NOTE:​ Service Studio allows you to Test REST API methods. This feature will also 
speed up the integration since the data type of the response can be automatically 
inferred. In situations where Test is not available or not possible you can set a 
sample Body response in the Body tab. Usually documentation provide some 
sample responses. 

For this particular case, the sample response found in the documentation is like 
this: 

​{ 
"ErrorMessage": "string", 
"Contacts": [ 
{ 
"Title": "string", 
"Name": "string", 
"Gender": "string", 
"Phone": "string", 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 9 
  

"Birthday": "2014-12-31", 
"Occupation": "string", 
"City": "string", 
"State": "string", 
"Country": "string", 
"Email": "string", 
"Company": "string" 
} 
], 
"Success": true 
} 

f) After clicking the Test button, the Response tab at the bottom should be 
populated with the data retrieved from invoking the REST API method. 

g) Click the ​Copy to Response Body​ button. The Body tab should now have the 
sample response obtained in the previous step. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 10 
  

h) Click the ​OK​ button to close the Consume REST API Method. 

i) Finally, change the name of the Integration from ​FoundationOutSystems t​ o 

ContactsAPI​. 

NOTE:​ This step is not mandatory, but it allows developers to have custom or 
more familiar names in their integrations. You may also change the names of the 
methods which can be useful when the auto-generated names are more 
unfamiliar. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 11 
  

j) Switch to the Data tab, and locate the ​ContactItem​ Structure under the 
ContactsAPI​. 

The C
​ ontactItem​ and ​GetContactsResponse ​structures were automatically created 
by Service Studio when the API Method was added in previous steps.  

Expanding the C
​ ontactItem​ structure allows you to see all attributes of Contact 
(Title, Name, Gender, …). These attributes were also automatically inferred by 
Service Studio from the sample response of the API method. 

k) Rename the structure to ​Contact​. 

NOTE​: Just like renaming the API method, this step is also not mandatory. 
However, renaming it makes development easier since names become more 
familiar. It also allows for Service Studio to automatically set variables data types 
based on their names. For Instance, when creating a variable named C
​ ontact​, 
Service Studio will automatically set its type to the ​Contact​ structure.   

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 12 
  

List Contacts on the screen 

According to the Screen lifecycle of OutSystems web applications, when the user is redirected 
to the Contacts Screen, firstly, the Preparation will be executed. Therefore, the Preparation of 
the Contacts Screen is where we will request the list of contacts from the external REST Service. 

In our sample app, the Contacts screen has already been created. Let’s now implement the 
Preparation that will retrieve the list of Contacts. 

1) In the Preparation of the Contacts screen, invoke the ContactsAPI to retrieve the list of 
contacts from the External REST Web Service. 

a) In the Interface tab, double-click the Preparation of the ​Contacts W

​ eb Screen to 
open it in the canvas.  

b) Switch to the Logic tab and locate the ​GetContacts​ REST method that we have 
just defined. Drag and drop the method on the Preparation. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 13 
  

2) Validate the result of the REST API method and show the error message on fail. 

a) Drag an ​If a
​ nd drop it after the ​GetContacts​, then set its ​Condition t​ o  

GetContacts.Response.Success 

b) Drag an ​End a
​ nd drop it to the right of the If, then create the True branch 
connector from the If to the new End. 

c) Drag a ​Run Server Action ​and drop it on the False branch connector of the If. 

d) In the ​Select Action​ dialog, choose the ​Feedback_Message​ action. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 14 
  

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 15 
  

e) Set the ​MessageText p

​ arameter to G
​ etContacts.Response.ErrorMessage​ and the 
MessageType t​ o ​Entities.MessageType.Error​. 

3) Now that we have a way to retrieve a list of records we need to create the interface to 
display them to the user. For that we are going to show them in a Table Records widget. 

a) Switching back to the Interface tab, double-click the ​Contacts S

​ creen to open it in 
the canvas. 

b) Drag and drop a ​Table Records​ to the Main Content. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 16 
  

c) Set the ​Source Record List​ property to 

GetContacts.Response.Contacts 

d) Let’s switch to the Data tab and under the Structures folder locate the ​Contact 
structure. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 17 
  

e) Drag the ​Name a

​ ttribute and drop it in the Table Records. 

 
f) Repeat the previous step for the ​Gender​, ​Occupation a
​ nd ​Company ​fields. 
g) You should end up having the Contacts screen with a Table Records with 4 
columns. 

 
 

4) Publish the application using 1-Click Publish button and verify that the publish 
completed successfully in the 1-Click Publish Tab. 

a) Click on the 1
​ -Click Publish button​ to publish the module to the server. 

b) Verify in the 1-Click Publish tab that the publishing process was successful. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 18 
  

c) Preview the app in browser by clicking on the Open in Browser​ button. 

d) The Contacts screen should be presented and display existing contacts. 

NOTE:​ The contacts shown may vary depending on the data provided by the 
external system. 

   

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 19 
  

End Lab 
In this lab, we integrated with a REST Web Service, namely a GET method to retrieve the list of 
Contacts provided by the external system. 

To accomplish that, we have used the OutSystems visual interface to consume the REST 
method, that automatically infers the output structure of the method. 

Once we consumed the API, we implemented the logic to display the information in the 
Contacts screen, firstly adding the method on the Preparation and then creating the interface 
to show some of the Contacts’ data on the screen. 

At the end of this exercise you should be able to integrate with a simple REST API to retrieve 
data and display it in your application. 

OutSystems Inc.​ 5
​ 901 Peachtree Dunwoody Road, N.E. Building C, Suite 495, Atlanta, GA 30328 20