Skip to main content

Parameter Extraction Algorithm

This document explains how Traces extracts parameter values from source endpoint responses and makes them available to dependent endpoints.

Overview​

When an endpoint depends on another endpoint's response, the system needs to:

  1. Find the relevant test result for the source endpoint
  2. Navigate to the correct location in the JSON response
  3. Apply any filter conditions (for conditional variables)
  4. Extract the value(s) to use as parameters

Source file: apps/web/src/lib/endpoint-testing.ts

The Extraction Pipeline​

Step 1: Find Relevant Mappings​

The system finds all mappings where the current endpoint is the target:

Target endpoint: GET /users/{userId}/posts

Relevant mappings:
  - sourceEndpointId: "list-users"
    sourceJsonPath: "data[*].id"
    targetParameter: "userId"
    targetParameterLocation: "path"
    mode: "iterate"

Step 2: Retrieve Source Test Result​

For each mapping, the system looks up the test result from the source endpoint:

testResults.get("list-users")
  -> { response: { responseData: { data: [{id: "u1"}, {id: "u2"}] } } }

If no test result exists, the mapping is skipped.

Step 3: Extract Value Using JSON Path​

The extractValueFromPath() function navigates the JSON structure using the source path.

Path parsing: The path is split on . and [ characters:

Path: "data[*].id"
Parts: ["data", "*", "id"]

Path: "users[0].profile.email"
Parts: ["users", "0", "profile", "email"]

Traversal rules:

PartAction
*If current is array, filter if applicable, then take first element
-1Take last element of array
0, 1, etc.Take specific array index
fieldNameAccess object property

Step 4: Apply Filter Conditions​

If the mapping originated from a conditional variable, the filter is applied at the last wildcard in the path.

Path: "data[*].children[*].id"
Filter: type = 'page'

Traversal:
  1. Enter "data" -> array
  2. First [*] -> iterate through data items (no filter yet)
  3. Enter "children" -> array
  4. Second [*] -> THIS IS LAST WILDCARD -> apply filter here
  5. Take first matching item
  6. Extract "id"

Why filter at the last wildcard? This matches how the UI works. When a user selects data[*].children[*].id and adds a filter, they're filtering the innermost array before extracting values.

Step 5: Group by Parameter Location​

The getParameterValuesByLocation() function returns values grouped by where they'll be used:

{
  path: { "userId": "u1" },      // For URL path substitution
  query: { "filter": "active" }, // For query string
  body: { "data": "value" }      // For request body
}

JSON Path Traversal Details​

The traversal function handles several special cases:

Array Wildcards​

Data: { items: [{ id: 1 }, { id: 2 }, { id: 3 }] }
Path: "items[*].id"

Without filter: Returns 1 (first element)
With filter (id > 1): Returns 2 (first matching element)

Nested Objects​

Data: { user: { profile: { name: "Alice" } } }
Path: "user.profile.name"

Returns: "Alice"

Array Indices​

Data: { items: [{ id: 1 }, { id: 2 }, { id: 3 }] }
Path: "items[1].id"

Returns: 2 (zero-indexed)

Path: "items[-1].id"
Returns: 3 (last element)

Missing Paths​

If any part of the path doesn't exist, the function returns undefined:

Data: { user: { name: "Alice" } }
Path: "user.profile.email"

Traversal:
  1. "user" -> { name: "Alice" }
  2. "profile" -> undefined

Returns: undefined (parameter skipped)

Key Code References​

Function (in endpoint-testing.ts)Purpose
getParameterValuesByLocation()Main entry point — returns values grouped by path / query / body
getParameterValuesFromMappings()Resolve mapping values for a target endpoint
extractValueFromPath()Core single-value traversal logic (path parsing, wildcard + filter handling)
isEndpointConfigured()Whether an endpoint's required params are all satisfied
note

Line numbers are omitted because this file is actively edited; search for the function name. Multi-value (iterate) extraction lives in extractAllValuesFromPath() in components/dependency-mapper/EndpointTestPanel.tsx — see JSON Path Extraction.

Iterate vs First Mode​

First Mode (Default for Testing)​

Takes the first matching value. Used during single endpoint tests.

Source: [1, 2, 3, 4, 5]
Result: 1

Iterate Mode​

Extracts ALL matching values. The dependent endpoint runs once per value.

Source: [1, 2, 3, 4, 5]
Result: [1, 2, 3, 4, 5]
Target runs: 5 times

The iterate extraction uses a different function (extractAllValuesFromPath() in EndpointTestPanel.tsx) that recursively collects all values instead of stopping at the first.

Debugging Tips​

"No value extracted"​

Check:

  1. Source endpoint has a test result with responseData
  2. JSON path matches the actual response structure
  3. Path uses correct notation ([*] for arrays, . for objects)

"Wrong value extracted"​

Verify:

  1. Path points to the correct field
  2. Array indices are correct (zero-indexed)
  3. For conditional variables, filter is selecting expected items

"Filter not working"​

Ensure:

  1. Filter condition field exists on array items
  2. Operator and value are appropriate for the data type
  3. Filter is on a variable used in the mapping (not a direct mapping)