# 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.


---

# 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/defining-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.