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


---

# 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.qyrus.com/data-testing/apis-and-webhooks/api-connector.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.