Query Parameter-Based Routing

Overview

Query parameter routing allows you to route requests to sandboxes by including the routing key in the URL as a query parameter. This provides a simple way to test sandboxed services without requiring header propagation or tracing instrumentation.

This is particularly useful for:

• Manual testing: Quickly test a sandbox by adding ?sd-routing-key=<key> to a URL in your browser
• API testing tools: Route requests from tools like curl, Postman, or MCP-based AI assistants without configuring custom headers
• Webhooks and callbacks: Route incoming webhook requests to sandboxes when you cannot control the headers sent by external services
• Sharing sandbox URLs: Send a colleague a link that routes directly to your sandbox

How It Works

When a request arrives at a service within a sandbox with the sd-routing-key query parameter:

https://api.example.com/users?sd-routing-key=my-sandbox-abc123
                              └──────────────────────────────┘
                                   routing key in query param

1. The routing layer matches the query parameter value against routing keys
2. The query parameter is stripped from the URL
3. The routing key is injected into standard headers (baggage, tracestate, custom)
4. The request continues with normal header-based routing

Incoming Request                          Downstream Request
      │                                         │
      ▼                                         ▼
┌──────────────────────┐              ┌──────────────────────┐
│ GET /users           │              │ GET /users           │
│ ?sd-routing-key=abc  │  ────────▶   │                      │
│                      │              │ baggage: sd-routing- │
│ (no routing headers) │              │   key=abc            │
└──────────────────────┘              └──────────────────────┘
       Query param                         Headers injected,
       present                             param stripped

This means query parameter routing seamlessly integrates with existing header-based routing, provided that the first service hit is inside the sandbox with the specified routing key. Once the routing key is injected into headers, subsequent service-to-service requests will route to the sandbox through normal context propagation.

Best-Effort Routing Key Propagation

Propagation of query parameter routing keys is best-effort. The exact behavior depends on your routing configuration (Istio, Gateway API, DevMesh). In some configurations, if the first service receiving the request is not forked by the sandbox specified in the routing key, the query parameter may not be converted to headers for downstream propagation.

Using Query Parameter Routing

Query Parameter routing can be useful in several scenarios and some examples follow. However because query parameters are not expected to propagate service to service, in order for them to work, the first service which receives the request must be inside the routing context for the sandbox with the specified routing key.

Once a service inside a sandbox receives a request with a query parameter routing key, all downstream requests will have the standard routing headers injected and there will be no difference in routing as compared to using routing headers.

With Browser Testing

For regular browser-based testing, the Signadot Chrome Extension is the recommended approach as it automatically injects routing headers for you.

However, query parameter routing is useful when you want to share a sandbox URL with a colleague who may not have the extension installed:

https://myapp.example.com/dashboard?sd-routing-key=my-sandbox-abc123

The recipient can open the link and immediately see the sandbox in action.

With API Testing Tools

In tools like curl, HTTPie, Postman, or MCP-based AI assistants (e.g., Claude with the Signadot MCP server), add the query parameter to your request URL:

# curl example
curl "https://api.example.com/users/123?sd-routing-key=my-sandbox-routing-key"

# HTTPie example
http GET "api.example.com/users/123?sd-routing-key=my-sandbox-routing-key"

For MCP-based tools, you can instruct the assistant to append the routing key when making requests to test sandbox changes.

With Webhooks

When configuring webhooks from external services, append the routing key to the callback URL:

Webhook URL: https://api.example.com/webhooks/payment?sd-routing-key=my-sandbox-abc

Incoming webhook requests will be routed to your sandbox for testing.

Query Parameter Name

The query parameter name is sd-routing-key. This matches the header key used for routing, making it easy to remember.

Obtaining the Routing Key

The routing key for a sandbox can be found in the Signadot dashboard or via the CLI:

signadot sandbox get <sandbox-name> -o json | jq -r '.routingKey'

Interaction with Header-Based Routing

Query parameter routing works alongside header-based routing. If a request contains both a routing key in a query parameter and in headers:

• The query parameter takes precedence
• The query parameter value is injected into headers, potentially overwriting existing routing key header values

For requests that already have proper header-based routing keys (e.g., from instrumented services), the query parameter is not needed.

When to Use Query Parameters vs Headers

Use Case	Recommended Approach
Service-to-service calls	Headers via context propagation
Browser testing (personal)	Chrome Extension
Sharing sandbox URLs	Query parameters
External webhooks	Query parameters
CI/CD integration tests	Headers (more reliable for automated testing)