HTTP

An HTTP connection defines a reusable client and baseUrl. Each generator defines one request template against that service.

The example below produces this request envelope without calling the API:

{
  "method": "POST",
  "url": "https://api.example.com/v1/orders/ORD-001?environment=demo",
  "headers": {
    "Content-Type": "application/json",
    "X-Source": "synthtraffic"
  },
  "body": {
    "orderId": "ORD-001",
    "status": "placed"
  }
}

Send order requests

connections:
  ordersApi:
    type: http
    baseUrl: https://api.example.com/v1

generators:
  - name: orders
    connection: ordersApi
    config:
      maxEvents: 2
    vars:
      orderId: =seq(format=ORD-%03d)
    method: POST
    path: /orders/$orderId
    query:
      environment: demo
    headers:
      Content-Type: application/json
      X-Source: synthtraffic
    body:
      orderId: $orderId
      status: placed

• connections.ordersApi stores the base URL and client limits.
• connection: ordersApi selects that client.
• path is required and is joined to baseUrl.
• method defaults to POST.
• query and headers add request metadata.
• body is the JSON request body. HTTP generators use body, not value.
• vars.orderId calculates a safe dynamic path segment and reuses it in the body.

Preview without calling the API

sample prints a short preview to your terminal. It does not wait for real-time pacing, and it never opens Kafka, PostgreSQL, or other destinations.

synthtraffic sample http.yaml --events 2 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/http.yaml:/work/http.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/http.yaml --events 2 --seed 42

run --stdout prints the destination-shaped envelope locally without opening the configured connection. Remove --stdout when you are ready to send to that destination.

synthtraffic run http.yaml --stdout --events 2 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/http.yaml:/work/http.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  run /work/http.yaml --stdout --events 2 --seed 42

Full flag lists: sample and run. Install and license: Install.

Both commands print {method, url, headers, body?} and do no network work. Fields with sensitive names and values derived from env() are redacted in previews.

Connection settings

baseUrl may include a path such as /v1, but it cannot include user information, query parameters, or a fragment. Only env() is allowed as a calculated connection value.

concurrency limits in-flight requests and applies backpressure when the limit is reached. timeout covers sending the request and completely reading the response.

There are no connection-level retry, authentication, header, or TLS configuration fields. HTTPS uses the operating system trust configuration; add tokens or API keys as generator headers.

Generator request fields

HTTP generators cannot use Kafka, PostgreSQL, or storage output fields such as topic, row, or prefix.

Path templates

A dynamic path reference must occupy a whole slash-separated segment:

vars:
  orderId: =format(ORD-%06d, seq())
path: /orders/$orderId

Synthtraffic URL-escapes both static and dynamic segments. A path cannot contain a query string, fragment, backslash, . or .. traversal segment, encoded separator, or authority form beginning with //. Functions do not run directly inside path; calculate a nested or composed value in vars and reference the result as $name.

Query parameters and headers

query and headers must be objects. Their values may be strings, numbers, booleans, decimals, or timestamps, but not null, objects, or lists.

Header names are static and case-insensitively unique. The transport manages these headers, so scenarios cannot set them:

Connection, Content-Length, Host, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailer, Transfer-Encoding, and Upgrade.

Authentication belongs in ordinary generator headers:

headers:
  Authorization: =concat('Bearer ', env(API_TOKEN))
  X-Tenant-Id: $tenantId

The token is evaluated for a connected run and redacted from preview output.

Body omitted versus null

Omitting body sends no body. Writing body: null sends the JSON value null. When a body is present and you did not set Content-Type, Synthtraffic adds application/json.

Delivery behavior

• Any received HTTP status, including 404 and 500, counts as delivered after the response body is read.
• Redirects are returned as responses and are not followed.
• DNS, connection, TLS, timeout, response-read, and response-close failures fail the run.
• The first asynchronous request failure stops accepting successful later work; accepted requests are flushed before a successful stage or run ends.
• Synthtraffic does not retry failed requests. Model repeated deliveries with Delivery behavior only when duplicates are intentional.

Send for real

Make sure the service is reachable, set any environment values, and remove --stdout:

synthtraffic run http.yaml --events 2 --seed 42

If the API treats non-2xx statuses as failures, it must return a connection/read error or you must verify application responses outside Synthtraffic; HTTP status alone does not fail a run.

Related

• Connection mental model: Connections
• Environment tokens: Strings and env
• Delays and duplicate deliveries: Delivery behavior
• Complete example: examples/connectors/http.yaml