Request Aggregation

Fan out a single client request to multiple upstream APIs in parallel, then merge the results into one response. Eliminate client-side orchestration and reduce round trips.

How It Works

When a request hits an aggregation route, Nolxy fires all configured upstream calls in parallel using Promise.allSettled. Each call has its own timeout. Results are merged into a single JSON response according to the configured merge strategy.

  1. Client sends one request to the aggregation endpoint
  2. Nolxy fans out to up to 10 upstream APIs simultaneously
  3. Each upstream has an independent timeout (default: 5s)
  4. Results are merged and returned as a single JSON object

Configuration

{
  "aggregation": {
    "mergeStrategy": "keyed",
    "timeoutMs": 5000,
    "calls": [
      {
        "key": "user",
        "url": "https://users-api.example.com/me",
        "method": "GET",
        "required": true
      },
      {
        "key": "orders",
        "url": "https://orders-api.example.com/recent",
        "method": "GET",
        "required": false
      },
      {
        "key": "notifications",
        "url": "https://notif-api.example.com/unread",
        "method": "GET",
        "required": false
      }
    ]
  }
}

Merge Strategies

keyed

Each upstream result is nested under its key. Failed optional calls return null for their key.

{ "user": {...}, "orders": [...], "notifications": null }
merge

All upstream results are shallow-merged into a single flat object. Later keys override earlier ones on conflict.

{ "id": 1, "name": "Alice", "orders": [...] }

Required vs Optional Calls

Mark a call as "required": true to fail the entire aggregation if that upstream fails or times out. Optional calls ("required": false) return null on failure without blocking the response.

Security & Performance

  • Maximum 10 upstream calls per aggregation.
  • Maximum response size per call: 5 MB.
  • Advanced SSRF Protection — Every upstream URL is asynchronously resolved by the gateway. Private IP ranges (including 0.0.0.0 and ::1) are strictly blocked to prevent server-side request forgery.
  • DNS Caching — To eliminate latency from repeated DNS lookups during parallel fan-out, safe resolutions are cached in a secure LRU cache.
  • Per-call timeout enforced independently.

Plan Requirements

Request Aggregation is available on Business plans only.

OIDC / OAuth2 Auth