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

# API Connector

> The API connector enables data retrieval from REST APIs with flexible configuration options, supporting authentication, pre-requisite calls, and advanced data extraction.

## Overview

Retrieve data from RESTful APIs for validation and comparison. The API connector supports:

* ✅ Multiple HTTP methods (GET, POST, PUT, DELETE)
* ✅ Custom headers and authentication
* ✅ Complex request payloads
* ✅ Pre-requisite API dependencies
* ✅ JSONPath and XPath data extraction
* ✅ JSON, XML, and other response formats

{% hint style="info" %}
Perfect for validating real-time data, testing API responses, and comparing data from service endpoints.
{% endhint %}

![API Connection Configuration](/files/jaxa8ZVsFXOZXgiiWBpj)

***

## ⚙️ Configuration Parameters

| Parameter         | Description                              | Required    |
| ----------------- | ---------------------------------------- | ----------- |
| **Source Name**   | Unique identifier for the API connection | ✅ Yes       |
| **Request Type**  | HTTP method (GET, POST, PUT, DELETE)     | ✅ Yes       |
| **URL**           | API endpoint address                     | ✅ Yes       |
| **Parameters**    | Query parameters as key-value pairs      | ⚠️ Optional |
| **Headers**       | Request metadata (auth, content-type)    | ⚠️ Optional |
| **Body**          | Request payload for POST/PUT (JSON)      | ⚠️ Optional |
| **Pre-requisite** | Dependent API calls (up to 2 levels)     | ⚠️ Optional |

***

## 🚀 Step-by-Step Configuration

### Step 1: Select API as Source Connection

{% hint style="info" %}
Start by selecting API as your data source connector type.
{% endhint %}

1. Navigate to **Start Job**
2. Select **API** under **Source Connection Type**
3. Enter a unique **Source Name** (e.g., `API1`, `CustomerAPI`)
4. Click ✅ to confirm

![API Source Selection](/files/p1MsRDvwnZEV8F7yQefN)

***

### Step 2: Configure API Request

Supply all necessary request configuration details:

```
Example GET Request:
├── URL: https://api.example.com/customers
├── Method: GET
├── Parameters: limit=100, offset=0
├── Headers: Authorization: Bearer {token}
└── Response: JSON array of customer objects
```

**Configuration Fields:**

1. Enter the **API Endpoint URL**
2. Select the appropriate **Request Type**
3. Add **Parameters** (key-value pairs) if required
4. Provide **Headers** for authentication or content type
5. Include **JSON Body** for POST/PUT requests
6. Configure **Pre-requisite** APIs if needed

![API Configuration](/files/p1MsRDvwnZEV8F7yQefN)

***

### Step 3: Pre-requisite APIs (Optional)

{% hint style="info" %}
Pre-requisite APIs are essential when the main API requires tokens or credentials with limited validity.
{% endhint %}

**Use Cases:**

| Scenario             | Solution                              |
| -------------------- | ------------------------------------- |
| **Token Expiration** | Pre-requisite refreshes access token  |
| **Dynamic Auth**     | Generate new credentials on-demand    |
| **Session Setup**    | Establish session before main call    |
| **Data Lookup**      | Fetch ID before using in main request |

**Configuration Steps:**

1. **Extract Value Path** – Specify JSONPath to extract values

   ```
   Examples:
   - $.access_token
   - $.body["token"]
   - $.users[0].id
   ```
2. **Variable Mapping** – Assign a variable name to extracted value

   ```
   Variable Name: auth_token
   ```
3. **Usage in Main API** – Reference with `#variable_name#` syntax

   ```
   Headers: Authorization: Bearer #auth_token#
   ```

{% hint style="warning" %}
**Support Levels:** Configure up to 2 levels of prerequisite APIs. All extracted values are available in the main API call.
{% endhint %}

![Pre-requisite API Configuration](/files/DPY5D8opxu33NYp2pHqn)

**📖 Example:** [View API Pre-requisite Demo](/data-testing/demo-walkthroughs/index/api-pre-requisite.md)

***

### Step 4: Execute the API Call

Click **Call API** to execute the configured request and receive the response.

![Call API](/files/z3uJhECMPukBm1AXQokA)

{% hint style="info" %}
Monitor the response status code and body for errors or unexpected data.
{% endhint %}

***

### Step 5: Extract Data from Response

Define extraction rules to parse API responses:

{% tabs %}
{% tab title="JSON Extraction" %}
Use **JSONPath** to extract specific fields:

```javascript
// Path: $.users[0].email
// Extracts: first user's email address

// Path: $.data[*].id
// Extracts: all IDs from data array
```

[JSONPath Reference](https://goessner.net/articles/JsonPath/)
{% endtab %}

{% tab title="XML Extraction" %}
Use **XPath** for XML responses:

```xml
<!-- Path: //user/email -->
<!-- Extracts: all email elements under user -->

<!-- Path: /root/users/user[1]/name -->
<!-- Extracts: first user's name -->
```

[XPath Reference](https://www.w3schools.com/xml/xpath_intro.asp)
{% endtab %}
{% endtabs %}

1. Use **Response Extractor** to define extraction rules
2. Select **Response Type** (JSON, XML, etc.)
3. Apply **JSONPath/XPath** to extract relevant values
4. Click **Extract** to preview the data

![Extract Data](/files/zgeHj23kEjcRT6sHSIW0)

***

### Step 6: Verify Extracted Data

* Click **Verify** to validate extracted values
* Preview the extracted dataset
* Proceed to next step if verification succeeds

***

## 📋 Supported Response Formats

| Format         | Extension | Extractor      | Support |
| -------------- | --------- | -------------- | ------- |
| **JSON**       | .json     | JSONPath       | ✅ Full  |
| **XML**        | .xml      | XPath          | ✅ Full  |
| **CSV**        | .csv      | Column mapping | ✅ Full  |
| **Plain Text** | .txt      | Regex          | ✅ Full  |

***

## 📊 JSON Data Structures

### Flat JSON

Perfect for simple tabular data:

```json
[
  {
    "UserId": "U001",
    "Food_Item": "Chicken Tenders",
    "Serving_Size_g": 574,
    "Calories": 269
  },
  {
    "UserId": "U002",
    "Food_Item": "French Fries",
    "Serving_Size_g": 450,
    "Calories": 365
  }
]
```

**Extraction:** Use direct field names or JSONPath expressions.

***

### Nested JSON

For hierarchical data structures:

```json
{
  "Users": [
    {
      "UserId": "U001",
      "Details": {
        "Food_Item": "Chicken Tenders",
        "Serving_Size_g": 574,
        "Calories": 269
      }
    }
  ]
}
```

**Extraction:** Use JSONPath like `$.Users[*].Details.Food_Item`

***

## ⚠️ Limitations & Constraints

{% hint style="warning" %}
**Response Size Limits:**

* **Comparison Jobs**: JSON responses > 6 MB
* **Configuration Functions**: Responses ≤ 6 MB
* **Table Functions**: Responses ≤ 6 MB

Exceeding limits may cause timeouts or errors.
{% endhint %}

### Timeout Management

| Scenario                | Timeout    | Action              |
| ----------------------- | ---------- | ------------------- |
| **Large responses**     | 30 seconds | Use pagination      |
| **Complex extraction**  | 30 seconds | Optimize JSONPath   |
| **Pre-requisite chain** | 60 seconds | Minimize call depth |

***

## 🔐 Authentication Methods

{% tabs %}
{% tab title="Bearer Token" %}

```
Header Name: Authorization
Header Value: Bearer {your_token_here}
```

{% endtab %}

{% tab title="API Key" %}

```
Header Name: X-API-Key
Header Value: {your_api_key}
```

{% endtab %}

{% tab title="Basic Auth" %}

```
Header Name: Authorization
Header Value: Basic {base64_encoded_credentials}
```

{% endtab %}

{% tab title="Custom Headers" %}

```
Header Name: {Custom-Header}
Header Value: {value}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Store sensitive credentials in environment variables or secrets management systems. Never hardcode tokens in configurations.
{% endhint %}

***

## 🎯 Common Use Cases

### Real-time Data Comparison

Compare API response with database snapshot to detect discrepancies.

### API Response Validation

Validate API returns correct data structure and types.

### Multi-source Aggregation

Combine data from multiple APIs for comprehensive validation.

### Service Health Monitoring

Regularly validate API responses for functionality and correctness.

***

## 📚 Related Documentation

* [API Pre-requisite Demo](/data-testing/demo-walkthroughs/index/api-pre-requisite.md)
* [API to File Demo](/data-testing/demo-walkthroughs/index/api-to-file.md)
* [Data Sources Overview](/data-testing/data-sources/index.md)
* [Create Compare Job](/data-testing/jobs-and-workflows/index/compare-job.md)