Query Parameters

Query parameters are key-value pairs appended to the URL (e.g., ?status=active&limit=100). This guide covers how to configure and use query parameters for testing endpoints.

Overview

Query parameters can come from:

1. Manual entry - Values you type for testing
2. Dependency mappings - Values extracted from other endpoints
3. Endpoint definition - Default parameters defined in the connector

Accessing Query Parameters

Parameters Area (under the URL bar)

1. Select an endpoint in the tree
2. The parameters area beneath the URL bar lists the endpoint's path parameters (auto-detected from {param} segments in the path) and its query parameters
3. Each parameter is shown as a drop zone for binding a value

Config Tab

Query parameters are defined on the endpoint in the Config tab:

1. Open the Config tab in the endpoint test panel
2. Add or remove query parameter definitions, and mark each required or optional

Defined query parameters then appear automatically in the parameters area under the URL bar, even before they have a value.

Adding Manual Parameters

Defining a Query Parameter

1. Open the Config tab for the endpoint
2. Add a query parameter definition (name, required/optional)
3. The parameter appears in the parameters area under the URL bar with a drop zone for values

Setting Values

Once a parameter exists, in the parameters area under the URL bar:

1. Click the parameter drop zone
2. Enter a manual value, or
3. Drop a variable/mapping from another endpoint

Manual values are tracked separately (manualParameterValues) and take priority over mapped values.

Parameter Sources

Manual Values

Type a value directly:

Parameter: status
Value: "active"
URL: /users?status=active

Best for:

• Testing specific scenarios
• Static values that don't change
• Debugging with known values

Dependency Mappings

Link to another endpoint's response:

Source: GET /config returns { defaultLimit: 100 }
Mapping: config.defaultLimit -> limit (query)
URL: /users?limit=100

Best for:

• Dynamic values from API responses
• Chained requests needing context
• Values that vary per environment

Reusable Variables

Apply a saved variable:

Variable: DefaultPageSize (value: 50)
Applied to: limit (query)
URL: /users?limit=50

Best for:

• Consistent values across endpoints
• Filtered/conditional values
• Well-documented parameter sources

Query vs Path Parameters

Aspect	Query Parameters	Path Parameters
Location	After ? in URL	In URL path
Example	/users?status=active	/users/{userId}
Optional	Usually yes	Usually required
Multiple values	Can repeat	One per placeholder

Path parameters example:

/users/{userId}/posts
userId = "123"
Result: /users/123/posts

Query parameters example:

/users?status={status}&limit={limit}
status = "active", limit = "50"
Result: /users?status=active&limit=50

Common Query Parameter Patterns

Filtering

/users?status=active&role=admin
/posts?author_id=123&published=true

Pagination

/items?limit=100&offset=0
/records?page=1&per_page=50
/data?cursor=abc123

Sorting

/users?sort=created_at&order=desc
/items?sort_by=name&sort_dir=asc

Field Selection

/users?fields=id,name,email
/posts?expand=author,comments

Parameter Priority

When the same parameter has multiple sources, priority is:

1. Manual values (highest) - Override everything
2. Dependency mappings - Next priority
3. Endpoint defaults - Lowest priority

This allows testing with specific values while keeping defaults for production.

Endpoint-Defined Parameters

Some endpoints have predefined query parameters:

In Endpoint Edit Modal

1. Open endpoint edit modal
2. Go to Query Parameters section
3. Add/remove parameters
4. Set whether required or optional

Visibility

Defined parameters automatically appear in the Parameters panel, even without mappings or manual values.

Testing with Query Parameters

Verify in URL Preview

Before sending:

1. Check the URL bar in test panel
2. Verify parameters are formatted correctly
3. Look for ?param=value&param2=value2

After Testing

The test result shows:

• Request URL: Full URL with parameters
• Response: API response to verify parameters worked

Debugging

If parameters aren't working:

1. Check URL preview for correct format
2. Verify no URL encoding issues
3. Confirm API expects query vs path parameter

Best Practices

Document Purpose

Add notes explaining what each parameter does:

• Why it's needed
• What values are valid
• Whether it's for testing only

Use Consistent Names

Match API documentation:

• page_size vs pageSize vs limit
• Exact spelling and casing matter

Test Edge Cases

Try different values:

• Empty string
• Special characters
• Very large/small numbers
• Missing vs null

Clean Up Test Parameters

Remove testing-only parameters before finalizing:

• Debug flags
• Test account IDs
• Override values

Troubleshooting

"Parameter not in URL"

1. Check parameter has a value (empty values may be omitted)
2. Verify parameter location is "query" not "path"
3. Look for typos in parameter name

"API ignores parameter"

1. Confirm API supports the parameter
2. Check parameter name matches exactly
3. Verify value format is correct

"URL encoding issues"

Special characters are automatically encoded:

• Space becomes %20
• & becomes %26

If encoding breaks the API:

1. Check if API expects unencoded values
2. Report issue for manual handling

Related Documentation

• Dependency Mapping - Linking parameters to sources
• Endpoint Configuration - Defining endpoints
• Testing Connectors - Full testing guide