# Using APIs

Once you have defined your APIs, you can connect them to your UI. In Digia, there are three primary ways to use an API depending on your needs.

## 1. FutureBuilder (Load on Render)

The [**FutureBuilder**](/ui-building-blocks/widgets/media-async-widgets/future-builder.md) widget is used to fetch data as soon as a widget is rendered on the screen.

### Best For

* **Page Load**: Fetching data when the user lands on a screen (e.g., getting User Profile on the Profile Page).
* **Widget Load**: Loading async data for a specific section (e.g., a "Trending Now" section on the Home Page).

### How to use

1. Drag a `FutureBuilder` widget onto your canvas.
2. In the properties panel, select the **API Call** you want to run.
3. **Bind Arguments**: If your API needs parameters (like `userId`), bind them to variables (e.g., `PageParams`).
4. **Handle States**: To manage different API states (Loading, Success, Failure), you can use a [**ConditionalBuilder**](/ui-building-blocks/widgets/layout-structure-widgets/conditional-builder.md) widget.
   * **Loading**: Show a Spinner or Skeleton loader.
   * **Success**: Show the actual content (access data via `apiResponse`).
   * **Error**: Show an Error message or Retry button.

## 2. Paginated List View (Infinite Scroll)

For lists that contain too much data to fetch at once (like a Social Feed or Product Catalog), use the [**PaginatedListView**](/ui-building-blocks/widgets/scrolling-widgets/paginated-listview.md).

### Best For

* Long lists where you need "Load More" functionality as the user scrolls.

### How to use

The widget handles the complexity of "page numbers" and "offsets" for you.

1. Select the `PaginatedListView` widget.
2. Bind it to an API that supports pagination (accepts `page` or `offset/limit` params).
3. Digia automatically calls the API for the next page when the user scrolls to the bottom.

## 3. Call REST API Action (Event Driven)

Use the [**Call Rest API Action**](/logic-and-interaction/actions/call-rest-api.md) when you need complete control over *when* the API is called.

### Best For

* **Button Clicks**: "Submit Form", "Login", "Add to Cart".
* **Fire & Forget**: Sending analytics or logs where you don't need to show the result immediately.
* **Chain Reactions**: Calling an API after a form validation succeeds.

### How to use

1. Select an interactive widget (like a Button).
2. Add an Action: **Call Rest API**.
3. Select which API to call.
4. **Handle Response**:
   * **On Success**: Store the result in a Variable (App/Page State) or Navigate to another page.
   * **On Failure**: Show a [Toast](/logic-and-interaction/actions/toast.md) or error dialog.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/data-and-state/api-integration/using-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.