# Call Rest API

The **Call REST API** action allows you to trigger a pre-configured API call directly from your app. It is typically used to send or retrieve data from a remote server based on user actions or events.

Refer to [Define API Calls](https://docs.digia.tech/logic-and-interaction/actions/broken-reference) on how to define and then use.

{% embed url="<https://www.youtube.com/watch?v=afWKuKP0Fow>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=afWKuKP0Fow>

***

#### ✅ Common Use Cases

* Submitting a form to a backend service
* Fetching dynamic data to update the UI
* Sending user input to an external system

***

#### ⚙️ Default Behavior

By default:

| Behavior                     | Description                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Source**              | The API call is executed using the selected `API Call`                                                                                   |
| **Success / Error Handling** | If `On Success` or `On Error` flows are configured, they are triggered conditionally based on the **response** and **success condition** |
| **Visual Feedback**          | No loading or error UI is shown automatically → use actions like **Show Toast** or **Show Loading** for user feedback                    |

***

#### 📦 Properties

| Property            | Type                 | Required | Description                                                     |
| ------------------- | -------------------- | -------- | --------------------------------------------------------------- |
| `API Call`          | Dropdown             | ✅        | Select the pre-configured API call to execute                   |
| `Success Condition` | Expression (Boolean) | ❌        | Optional expression to determine if the API call was successful |
| `On Success`        | Action Flow          | ❌        | Actions to execute when the API call succeeds                   |
| `On Error`          | Action Flow          | ❌        | Actions to execute when the API call fails                      |

***

#### 📦 How to use

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-4d230f1cfc49c3b997a40130728eb0f609971f81%2Fcall_rest_api_action.png?alt=media" alt="Call External Method action configuration showing message name and payload fields"><figcaption><p>Call External Method action configuration in Digia Studio</p></figcaption></figure>

1. Add the action to a widget (e.g. on form submission or button click)
2. Choose **Call REST API** from the action list
3. Select the desired `API Call`
4. (Optional) Configure a **success condition** expression to determine success/failure
5. (Optional) Configure **On Success** and **On Error** flows based on the API outcome

***

#### 📦 Response Payload (Available in Expressions)

When the API call completes, the response is made available as a `response` variable with the following fields:

| Field        | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `body`       | The response body data                                                   |
| `statusCode` | The HTTP status code of the API response                                 |
| `headers`    | The response headers as a map                                            |
| `requestObj` | Details about the request (URL, method, headers, data, query parameters) |
| `error`      | Error message (if any) - `null` for successful responses                 |

You can access these fields in expressions using `response.body`, `response.statusCode`, etc.

***

#### 🎯 Success Condition

The **success condition** is an optional expression that determines whether the API call is considered successful. If not configured, all responses are treated as successful.

**Example expressions:**

* `isEqual(response.statusCode, 200)` - Success only on HTTP 200
* `and(gte(response.statusCode, 200), lt(response.statusCode, 300))` - Success on 2xx status codes
* `isEqual(jsonGet(response.body, 'success'), true)` - Success based on response body content

***

#### 💡 Examples

**Basic API Call with Response Handling:**

* Select "getUserData" as the API Call
* Add Set App State action in On Success to store `response.body`

**Conditional Success Based on Response:**

* Select "submitForm" as the API Call
* Set success condition: `and(isEqual(response.statusCode, 200), isEqual(jsonGet(response.body, 'status'), 'success'))`
* Add Show Toast action in On Success with success message
* Add Show Toast action in On Error with dynamic error message

**Error Handling in On Error Flow:**

* Select "updateProfile" as the API Call
* Add Show Toast action in On Error with error message

***

#### 🔗 Related Documentation

* [Setting up API Calls](https://docs.digia.tech/logic-and-interaction/actions/broken-reference) - How to configure API calls for use with this action
* [Create API Calls](https://docs.digia.tech/logic-and-interaction/actions/broken-reference) - Creating and managing API call configurations
* [Show Toast](https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/actions/show-toast.md) - Display user feedback messages
* [Set App State](https://docs.digia.tech/logic-and-interaction/actions/set-app-state) - Update application state with API response data

***