# How to Consume REST APIs in OutSystems Step by Step

- Tool: OutSystems
- Difficulty: Beginner
- Time required: 15-20 min
- Compatibility: OutSystems 11 and ODC
- Last updated: March 2026

## TL;DR

To consume a REST API in OutSystems, go to Logic tab → Integrations → REST → right-click → Consume REST API. Add a single method or import an OpenAPI spec. Service Studio auto-generates the action, input/output structures, and data type mappings. Drag the generated action into a Server Action flow to call it from your app.

## Calling External REST APIs from OutSystems

OutSystems makes it straightforward to integrate with any HTTP-based REST API through its built-in Import REST API wizard. When you point Service Studio at an endpoint or an OpenAPI spec, it generates typed actions and data structures automatically — no manual JSON parsing required. This tutorial walks through importing an endpoint, understanding the generated structures, and wiring everything up to a screen so real API data appears for your end users.

## Before you start

- OutSystems 11 Personal Edition or licensed environment, or ODC Studio access
- Basic familiarity with Service Studio (Logic tab, Server Actions)
- The URL of the REST API you want to consume (or use the public JSONPlaceholder API: https://jsonplaceholder.typicode.com)
- API credentials if the endpoint requires authentication (API key, Bearer token)

## Step-by-step guide

### 1. Open the Consume REST API wizard

In Service Studio, click the Logic tab on the right-hand panel. Expand Integrations. Right-click REST and select Consume REST API. A dialog appears with two options: Add Single Method (for one endpoint at a time) or Add Multiple Methods (for OpenAPI/Swagger specs). For a quick start, choose Add Single Method.

**Expected result:** The Consume REST API dialog is open and the method URL field is visible.

### 2. Configure the method URL and HTTP verb

In the Method URL field, enter the full endpoint URL. Use curly braces for path parameters — for example: GET https://jsonplaceholder.typicode.com/posts/{id}. Service Studio automatically creates an input parameter called Id (Integer) based on the {id} placeholder. Set the HTTP Method dropdown to GET, POST, PUT, or DELETE as appropriate. In the Headers/Auth tab, add any required headers such as Authorization or X-API-Key.

**Expected result:** The method URL is entered with correct path parameters highlighted, and the HTTP method is set.

### 3. Test the endpoint in Service Studio and copy the response

Click the Test tab inside the dialog. Fill in any required input parameters (e.g., enter 1 for {id}). Click the Test button. Service Studio makes a live HTTP call and displays the raw JSON response. Click Copy to Response Body — this populates the Response tab with the actual JSON payload. Service Studio uses this sample to generate the output structure with correct field names and data types.

**Expected result:** The Response tab is populated with sample JSON. Data types shown for each field (Text, Integer, Boolean, etc.) are correct.

### 4. Review and confirm auto-generated structures

Click the Response tab to review the mapping. Service Studio converts JSON types to OutSystems types: string → Text, number → Integer or Decimal, boolean → Boolean, object → Structure, array → List. Rename any generated structures or attributes if needed by clicking directly on them. Verify the output structure matches the shape of data you expect to use in your app. When satisfied, click OK to complete the import.

Service Studio creates: the REST API node under Logic tab → Integrations → REST, a method action (e.g., GetPost), input/output parameters, and any Structures under Data tab → Structures.

**Expected result:** Under Logic tab → Integrations → REST, your new API appears with the imported method listed beneath it. Structures appear under Data tab → Structures.

### 5. Call the API in a Server Action

Go to Logic tab → Server Actions → right-click → Add Server Action. Name it, for example, FetchPost. Add an input parameter PostId (Integer) and output parameter PostData (the generated output structure type). Inside the action flow, drag the generated method action (GetPost) from the toolbox or from Integrations → REST → [YourAPI] into the flow between Start and End. Set the method's Id input to PostId. Add an Assign node after the method call. In the Assign, set PostData = GetPost.Response.

Action flow: Start → GetPost (Id = PostId) → Assign (PostData = GetPost.Response) → End

**Expected result:** The Server Action compiles without TrueChange errors. The action is callable from screens or other Server Actions.

### 6. Display API data on a screen

Open (or create) a Reactive Web screen. Right-click the screen name → Fetch data from Other Sources — this creates a Data Action. Inside the Data Action, drag your FetchPost Server Action into the flow. Pass an appropriate PostId value (e.g., a screen input parameter or a hardcoded value like 1). Add an Output Parameter to the Data Action that holds the returned structure.

Back on the screen canvas, drag Expression widgets from the toolbox and set their Value to reference fields from the Data Action output — for example: DataAction1.PostData.Title. 1-Click Publish (Ctrl+F5) to deploy.

**Expected result:** After publishing, opening the screen in the browser displays live data fetched from the external REST API.

### 7. Handle errors from the API call

REST calls can fail (network issues, server errors, bad credentials). In your FetchPost Server Action, right-click the flow after the GetPost method call → Add Exception Handler → select Communication Exception. Inside the handler, add a Raise Exception node or an Assign that sets an error output parameter. Alternatively, wrap the API call in a try-style pattern: add an Exception Handler for AllExceptions at the Server Action level and log the error using the LogError system action from the (System) module.

Action flow with error handling: Start → GetPost → [Exception Handler: Communication Exception] → Assign ErrorMessage → End

**Expected result:** The Server Action handles network and timeout errors gracefully without crashing the app or exposing raw error details to users.

## Complete code example

File: `FetchPost_ServerAction_logic_pseudocode.txt`

```plaintext
/* Server Action: FetchPost
   Input:  PostId (Integer)
   Output: PostData (GetPost_Response structure)
           IsSuccess (Boolean)
           ErrorMessage (Text)
*/

Start
  |
  v
[GetPost]  -- REST method: GET /posts/{id}
  Id = PostId
  |
  v
[Assign]
  PostData     = GetPost.Response
  IsSuccess    = True
  ErrorMessage = ""
  |
  v
End

/* Exception Handler: Communication Exception */
[Assign]
  IsSuccess    = False
  ErrorMessage = "Unable to reach the API. Please try again."
  PostData     = Default(GetPost_Response)
  |
  v
End

/* Exception Handler: AllExceptions */
[LogError]
  Module  = "MyModule"
  Message = AllExceptions.ExceptionMessage
  |
[Assign]
  IsSuccess    = False
  ErrorMessage = "An unexpected error occurred."
  |
  v
End
```

## Common mistakes

- **Calling the REST API method from a Client Action instead of a Server Action** — undefined Fix: REST API calls run server-side. In Reactive apps, drag the method into a Server Action or Data Action, then call that from your Client Action. Calling it directly from a Client Action will cause a TrueChange error: 'REST API methods can only be used in server actions.'
- **Not testing the endpoint before importing, resulting in wrong data types on generated structures** — undefined Fix: Always use the Test tab in the Consume REST API dialog and click 'Copy to Response Body' before clicking OK. This gives Service Studio a real sample payload to generate accurate type mappings.
- **Hardcoding the API base URL in the method URL field** — undefined Fix: Extract the base URL into a Site Property (O11: Data tab → Site Properties) or Setting (ODC: ODC Portal). The method URL should only contain the path component (e.g., /posts/{id}). The base URL can then be changed per environment in Service Center without redeploying.
- **Ignoring TrueChange warnings about missing exception handlers on REST calls** — undefined Fix: TrueChange shows an orange warning when a Server Action containing a REST call has no Communication Exception handler. Add one — right-click the flow → Add Exception Handler → Communication Exception — and show the user a meaningful error message.

## Best practices

- Always test the endpoint in the Service Studio Test tab before importing — this ensures the generated structure matches the real API response.
- Store base URLs in Site Properties (O11) or Settings (ODC) rather than hardcoding them in the method URL. This allows environment-specific overrides without redeploying.
- Set the Timeout in Seconds property on each REST method to a value appropriate for the API's SLA — the default is 100 seconds, which may be too long for interactive requests.
- Never call consumed REST API actions from Client Actions — always call them from Server Actions to avoid CORS errors and to keep credentials server-side.
- Add a Communication Exception handler to every Server Action that calls an external API. Silent failures confuse users and are hard to debug.
- Use the OnBeforeRequest callback to inject authentication headers (Bearer token, API key) dynamically rather than hardcoding them in method headers.
- Set Max Records on any Aggregate that processes API response lists to prevent unbounded memory usage.
- Check Service Center → Monitoring → Integrations logs when debugging API calls — it shows request/response details, timing, and errors.

## Frequently asked questions

### Can I consume a REST API that requires OAuth2 authentication in OutSystems?

Yes. In the Consume REST API dialog, select the Authorization tab and choose OAuth 2.0. Enter your Authorization Server URL, Client ID, Client Secret, and Scopes. OutSystems handles the client credentials token fetch automatically. For more complex OAuth flows (authorization code, PKCE), use the OnBeforeRequest callback to manually attach a previously-obtained Bearer token.

### How do I update a consumed REST API when the external API changes its response format?

Right-click the REST API node under Logic tab → Integrations → REST → Refresh REST API. Service Studio re-imports the spec or re-tests the endpoint and highlights any structural changes. Review the diff, update any Assign nodes that reference renamed or removed fields, and resolve TrueChange errors before republishing.

### What happens if the external API returns an empty response body on success (HTTP 204)?

Service Studio handles 2xx responses with empty bodies without error. The output structure will simply have all fields at their default values. If you check for a non-null response body, handle this case explicitly by checking the HTTP status code via the OnAfterResponse callback rather than checking structure fields.

---

Source: https://www.rapidevelopers.com/outsystems-tutorial/outsystems-rest-api-consume
© RapidDev — https://www.rapidevelopers.com/outsystems-tutorial/outsystems-rest-api-consume