> For the complete documentation index, see [llms.txt](https://docs.digia.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digia.tech/data-and-state/api-integration/defining-apis.md).

# Defining APIs

This section guides you through defining your API endpoints on the Digia Dashboard.

## Environments

Before defining individual APIs, it is best practice to set up **Environments**.

* **Concept**: Environments allow you to define global variables that change based on where you are running the app (e.g., Local, Staging, Production). This is similar to **Postman Environments**.
* **Usage**: The most common use case is defining a `baseUrl`.
  * *Dev*: `https://dev-api.myapp.com`
  * *Prod*: `https://api.myapp.com`

## Adding a New API

1. Go to the **API** tab in your Project Dashboard.
2. Click **+ Add API**.
3. Fill in the details:
   * **Method**: GET, POST, PUT, PATCH, DELETE.
   * **URL**: The endpoint address.
   * **Headers**: Key-value pairs (e.g., `Content-Type: application/json`).
   * **Body**: The JSON payload (for POST/PUT).
   * **Response**: Digia automatically parses the JSON response to understand its structure.

> \[!NOTE] **Query Parameters**: There is no separate section for query params. Simply append them to the URL (e.g., `/users?limit=10`).

## API Variables

**API Variables** make your API calls dynamic. Think of an API definition as a **Function**, and API Variables as the **Parameters** (arguments) you pass to that function.

* **Purpose**: To pass data from your app (like user input or auth tokens) into the API call.
* **Scope**: These variables are local to the API definition.
* **Important**: You **cannot** access Global properties (like `AppState` or `UserAuth`) directly inside the API definition. You must define a variable (e.g., `token`) and pass the value in when you *call* the API.

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

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

### 1. Define the Variable

In the **Variables** tab of your API settings, add a new variable:

* Name: `userId`
* Type: `String`

### 2. Use the Variable (Binding)

Once defined, you can inject the variable into your URL, Headers, or Body using **Mustache Syntax** `{{ }}`.

* **URL**: `{{ baseUrl }}/users/{{ userId }}`
* **Header**: `Authorization: Bearer {{ token }}`
* **Body**:

  ```json
  {
    "amount": {{ cartTotal }},
    "currency": "USD"
  }
  ```

Both **Environment Variables** (like `baseUrl`) and **API Variables** (like `userId`) are used in the exact same way.

## Testing

Always test your API directly in the dashboard before using it in the app.

1. Go to the **Test API** tab.
2. Enter sample values for your variables.
3. Click **Run**.
4. Verify the status code and response body. This allows Digia to "learn" the response schema for binding.