---
description: Creating and Configuring API Test Steps in FinalRun
---

# Add API

Think of a test that first gets a token or ID from an API, then uses that value in a mobile step—or a mobile step that grabs some data and sends it back to the server to check. FinalRun’s **Add API** step makes this easy: you call an endpoint, check the response, and save a value as a variable for your next mobile action. Or you can take data from your mobile test (like an order ID) and send it to an API to confirm it on the backend. This guide shows you exactly how to add and use the API step in FinalRun.

***

####

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

#### Overview and Prerequisites

**Why Use API Steps?**

* **Setup Test Data:** Populate your application state before executing UI interactions.
* **Verify Backend Logic:** Ensure endpoints return expected results before proceeding with front-end validation.
* **Fetch Dynamic Values:** Extract tokens, IDs, or other data to drive subsequent test steps.

**Prerequisites:**

1. **FinalRun Account & Project:** Ensure you have a project with at least one test case created.
2. **Endpoint Details:** Know the API URL, supported HTTP methods, required headers, authentication scheme, and sample payloads.
3. **Network Access:** Confirm that your machine can reach the target endpoint (e.g., no VPN or firewall blocking).

***

#### 2. Adding an API Step

1. **Navigate to Test Steps:**
   * Open your test case and scroll to the Test Steps section.
   * Click on the **`Select a step`** dropdown.
2. **Choose “Add API”:**
   * From the list of available steps, select **`Add API`**.
   * The API request builder appears.

> **Tip:** If you frequently add API steps, consider creating a reusable template with common headers (e.g., Authorization) in your settings.

***

#### 3. Configuring Your API Request

**3.1 Select HTTP Method**

* Available options: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
* **Example:** For a read-only fetch, choose **`GET`**.

**3.2 Enter the Endpoint URL**

* In the **URL** field, paste or type the full endpoint (e.g., `https://jsonplaceholder.typicode.com/todos/1`).

**3.3 Add Params, Headers, and Body (Optional)**

* **Params Tab:** Add query parameters as key–value pairs.
* **Authorization Tab:** Select an auth type (e.g., Bearer Token, Basic Auth). Enter credentials or tokens.
* **Headers Tab:** Define custom headers (e.g., `Content-Type: application/json`).
* **Body Tab (for POST/PUT/PATCH):** Enter raw JSON, form-data, or other supported payload formats.

> **Example:** To create a new TODO item:
>
> ```
> {
>   "userId": 1,
>   "title": "Buy groceries",
>   "completed": false
> }
> ```

**3.4 Sending the Request**

* Click the **`Send`** (or **`Hit API`**) button located at the bottom-right.
* Wait for the response; the **Response Data** pane populates with status, headers, and body.

***

#### 4. Validating the API Response (Assertions)

Use assertions to verify that the API behaves as expected.

**4.1 Status Code Validation**

1. **Switch to the `Status` Tab:** Shows the HTTP status (e.g., 200 OK).
2. **Hover & Click “Validate”:** A dialog opens pre-filled with the current status code.
3. **Adjust Comparison Logic (Optional):** Change operators (e.g., `==`, `>=`).
4. **Click `Create`:** The assertion appears under the step summary (e.g., **Status == 200**).

> **Best Practice:** Always assert that status codes are in the 2xx range for successful requests.

**4.2 Header Validation**

1. **Switch to the `Headers` Tab:** Lists all response headers.
2. **Identify Target Header (e.g., `x-ratelimit-limit`):**
3. **Hover & Click “Validate”:** A dialog pre-fills the header and its value.
4. **Click `Create`:** Assertion appears (e.g., **x-ratelimit-limit >= 1000**).

> **Note:** Header names are case-insensitive. Use exact keys from the response.

**4.3 Body Validation with AI JSONPath Helper**

1. **Go to the `Body` Tab:** Displays the raw JSON response.
2. **Click “Validate” Next to JSON View:** Opens the validation dialog.
3. **Select “Use AI” Button:** An input box appears.
4. **Type a Natural-Language Query (e.g., `extract completed`):** AI generates a JSONPath expression (e.g., `$.completed`).
5. **Verify & Adjust “Expected Value” Field:** AI populates this based on current response (e.g., `false`).
6. **Click `Create`:** Assertion is saved under the step (e.g., **$.completed == false**).

> **Pro Tip:** Use AI for complex nested fields (e.g., `extract user’s company name`) to avoid manual JSONPath errors.

***

#### 5. Extracting Data into Variables

Saving parts of the response to variables makes your tests dynamic.

**5.1 Extract Status Code**

1. **Switch to the `Status` Tab:**
2. **Hover & Click “Extract Value”:** Opens extraction dialog.
3. **Name Your Variable (e.g., `statusCode`):**
4. **Click `Extract`:** The status code is stored in `{{statusCode}}` for later use.

> **Usage:** In a subsequent HTTP request, you could reference `{{statusCode}}` to assert dependencies.

**5.2 Extract from Body with AI**

1. **Go to the `Body` Tab:**
2. **Click “Extract Value” Next to JSON View:** Opens extraction dialog.
3. **Click “Use AI”:** Type a plain-English extraction request (e.g., `extract title`).
4. **AI Suggests JSONPath (`$.title`):** Review and confirm the path.
5. **Enter Variable Name (e.g., `todoTitle`):**
6. **Click `Extract`:** Value from `$.title` is saved in `{{todoTitle}}`.

> **Example:** If the response is:
>
> ```
> {
>   "userId": 1,
>   "id": 1,
>   "title": "Buy groceries",
>   "completed": false
> }
> ```
>
> extracting `title` stores "Buy groceries" in `{{todoTitle}}`.

***

#### 6. Example Walkthrough: Creating & Validating a TODO

1. **Add API Step** → **Select `GET https://jsonplaceholder.typicode.com/todos/1`**.
2. **Send Request** → Observe `200 OK`, response body displays TODO fields.
3. **Validate Status** → Assert **`Status == 200`**.
4. **Validate Body Field** → Use AI helper: “`extract completed`” → Assert **`$.completed == false`**.
5. **Extract Values** → Extract `id` into `todoId`, extract `title` into `todoTitle`.
6. **Save Step** → Step summary shows two assertions (`Status == 200`, `$.completed == false`) and two extractions (`{{todoId}}`, `{{todoTitle}}`).

> **Screenshot Placeholder:**
>
> 1. **API Request Builder** showing URL, method.
> 2. **Response Pane** with status, headers, body.
> 3. **Validations & Extractions** UI highlighting AI JSONPath helper.

***

#### 7. Best Practices & Troubleshooting

* **Consistent Variable Naming:** Use descriptive, camelCase names (e.g., `userId`, `authToken`).
* **Chain API Steps Carefully:** If one API depends on data from another, ensure extraction is done before referencing the variable.
* **Validate Critical Fields First:** Always assert status code before deeper validations to catch errors early.
* **Use AI Helper Sparingly:** For very simple fields, manual JSONPath (`$.fieldName`) may be faster.
* **Error Handling:** If an API returns an unexpected schema, adjust your JSONPath or API configuration to match the actual response.
* **Timeouts & Retries:** Configure request timeouts and retry logic in project settings if endpoints are unstable.

***

#### 8. Finalizing and Saving Your Test Case

1. **Review All Assertions & Extractions:** Scroll to the bottom of the API step builder; ensure every item is correct.
2. **Click `Create`:** Adds the fully configured API step to your test case.
3. **Save Test Case:** In the top-right, click **`Save Changes`** to persist your test.
4. **Run the Full Test Suite:** Verify that API steps integrate seamlessly with UI steps.

***

#### 9. Summary

This improved documentation offers a structured approach, practical tips, and clear examples for configuring API test steps in FinalRun. By following these guidelines, you can:

* Rapidly add and configure API steps.
* Assert response correctness with minimal effort.
* Extract dynamic values for robust, data-driven testing.

Continue experimenting with different endpoints and complex scenarios to fully leverage FinalRun’s API testing capabilities.

***

_For questions or feedback, reach out to the FinalRun support team or consult the official knowledge base._
