# API Chaining

{% hint style="info" %}
**Who is this for?** Developers and SDETs who need to pass data between API calls — such as capturing an auth token and injecting it into subsequent requests or UI steps.
{% endhint %}

API chaining lets you build multi-step request sequences where the output of one call becomes the input of the next. The most common pattern is authentication: a login endpoint returns a short-lived access token that must be injected into every subsequent request. Because the token expires quickly, you cannot hard-code it — chaining is the correct approach.

ContextQA also supports hybrid chains where a value extracted from an API response is passed directly into a UI interaction, and vice versa.

## How chaining works

Every API step stores its full response — status code, headers, and body — in a named variable that you define in the **Store response** field. The variable is available to every step that follows it in the same test case execution. Fields within the stored response are accessed using dot notation:

```
result.body.access_token
result.body.firstName
result.headers.content-type
```

Any subsequent step — API or UI — can reference these paths using `${variable_name.path}` syntax.

## Practical example: POST /auth then GET /protected-endpoint

### Step 1 — Authenticate and capture the token

1. Add an API step. Set the HTTP method to **POST** and enter the authentication endpoint URL (for example, `https://api.example.com/auth`).
2. In the request body, supply the login credentials.
3. Under **Store response**, enter `result`. This stores the full auth response.
4. In **Validation**, add a status code assertion: `status` **equal** `200`.
5. Click **Create** to save the step.

After the step runs, the access token returned by the endpoint is available as `result.body.access_token` (adjust the path to match your actual response structure).

### Step 2 — Call the protected endpoint with the token

1. Add a second API step. Click **Rest API method**.
2. Open the three-dot panel and paste the protected endpoint URL.
3. In **Headers**, add an `Authorization` key with the value `Bearer ${result.body.access_token}`.
4. Under **Store response**, enter a new variable name, for example `result1`.
5. Add a status code assertion: `status` **equal** `200`.
6. Click **Create** to save.

When the test suite executes, both steps complete. ContextQA resolves the `${result.body.access_token}` reference at runtime using the live token from step 1, so the assertion in step 2 passes even though the token value changes between runs.

## Hybrid API + UI chaining

Values extracted from an API response can be injected directly into UI actions. This enables data-driven UI tests that do not rely on hard-coded test fixtures.

**Example:** After the two API steps above, add a UI step that navigates to a web page and enters a value from the API response into a form field.

1. Add a UI step with the **Navigate** action and enter the target URL.
2. Add another UI step to type into an input field. When entering the value, reference the API response using dot notation — for example, `result1.body.firstName`.
3. Provide the field's metadata (element label, role, or other locator context) so ContextQA can find it.
4. Click **Create** to save.

When the test runs, ContextQA reads `firstName` from the API response captured in `result1` and types it into the correct UI element. This confirms that data returned by the API actually appears in the interface.

## Extracting specific fields

When constructing a JSON path for chaining, use **Run History** to find the exact path:

1. Run the test case once.
2. Open **Run History** and select the step.
3. Navigate to the **Response Body** tab.
4. Locate the field you want to extract. The full path from the variable root (for example, `result.body.data.id`) is what you enter in subsequent steps.

## Error handling in chained sequences

If an earlier step in a chain fails — for example, the auth endpoint returns a `401` instead of `200` — ContextQA stops the execution of that test case and marks all downstream steps as not run. This prevents false failures caused by missing variable values rather than actual bugs in the downstream API.

To make a chained sequence robust:

* Always include a status code assertion on the step that produces the variable. A failing assertion surfaces the root cause (the auth step) rather than a confusing downstream error.
* Use descriptive variable names (`authResult`, `userResult`) rather than generic names (`result`, `result1`) to make step references easier to read and debug.
* When a chain breaks, check **Run History** for the first failed step — that is where the root cause will be, not in the steps that never ran.

{% hint style="info" %}
**Generate API tests from your Swagger spec in minutes.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA generate and execute REST API tests for your backend.
{% endhint %}


---

# 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://learning.contextqa.com/api-testing/api-chaining.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.