Retrieving Data from a REST API (GET)

Table of Contents
Introduction........................................................................................................................2
Connect to an Environment 2

Get to know the scenario.................................................................................................. 5

Install the Contacts application 5
Business Case Overview 5

Define the REST API Method - GET....................................................................................6

List Contacts on the Screen.............................................................................................14

End Lab.............................................................................................................................. 22

[email protected] © 2021 by OutSystems. All rights reserved. OutSystems is a registered trademark of OutSystems. The information contained
herein is subject to change without notice. All terms and conditions for OutSystems products and services are set forth in the
www.outsystems.com agreements accompanying such products and services. Nothing herein should be construed as constituting an additional
warranty. OutSystems shall not be liable for technical or editorial errors or omissions contained herein.
 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 dialog. This can
be done in two ways.

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

Environment.

www.outsystems.com • [email protected] 2
 b) If you are already logged in to an environment, select the Switch
Environment... option from the Environment menu at the top.

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 Personal Environment tab the
environment address (or Server Address) can be found.

www.outsystems.com • [email protected] 3
 c) Back in Service Studio, use that Environment and login with your
OutSystems community email (username) and password.

www.outsystems.com • [email protected] 4
 Get to know the scenario
Install the Contacts application
Open and publish the REST 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.

www.outsystems.com • [email protected] 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 REST Contacts Web application and open
it.

www.outsystems.com • [email protected] 6
 b) Open the RESTContacts module

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

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

www.outsystems.com • [email protected] 7
 b) On the new window, click the Add Single Method button.

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 to

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

www.outsystems.com • [email protected] 8
 d) Keep the HTTP Method to GET.

e) Switch to the Test tab, then click the Test button

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:

www.outsystems.com • [email protected] 9
 ```
{
"ErrorMessage": "string",
"Contacts": [
{
"Title": "string",
"Name": "string",
"Gender": "string",
"Phone": "string",
"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.

www.outsystems.com • [email protected] 10
 g) Click the Copy to Response Body button. The Body tab should now have
the sample response obtained in the previous step.

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

i) Finally, change the name of the Integration from FoundationOutSystems to

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

www.outsystems.com • [email protected] 11
 names of the methods which can be useful when the auto-generated
names are more unfamiliar.

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

The ContactItem and GetContactsResponse structures were automatically

created by Service Studio when the API Method was added in previous
steps.

Expanding the ContactItem 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.

www.outsystems.com • [email protected] 12
 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 Contact, Service Studio will automatically set its type to the Contact
structure.

www.outsystems.com • [email protected] 13
 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 Web

Screen to open it in the canvas.

www.outsystems.com • [email protected] 14
 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.

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

a) Drag an If and drop it after the GetContacts, then set its Condition to

GetContacts.Response.Success

b) Drag an End and 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.

www.outsystems.com • [email protected] 15
 d) In the Select Action dialog, choose the Feedback_Message action.

www.outsystems.com • [email protected] 16
 e) Set the MessageText parameter to GetContacts.Response.ErrorMessage
and the MessageType to 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 Screen to

open it in the canvas.

www.outsystems.com • [email protected] 17
 b) Drag and drop a Table Records to the Main Content.

c) Set the Source Record List property to

GetContacts.Response.Contacts

www.outsystems.com • [email protected] 18
 d) Let's switch to the Data tab and under the Structures folder locate the
Contact structure.

www.outsystems.com • [email protected] 19
 e) Drag the Name attribute and drop it in the Table Records.

f) Repeat the previous step for the Gender, Occupation and 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.

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

www.outsystems.com • [email protected] 20
 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.

www.outsystems.com • [email protected] 21
 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.

www.outsystems.com • [email protected] 22