API Reference - Advanced Echo Server

Core Endpoints

GET / (any path not matching special routes)

Basic echo endpoint - returns request info for GET, mirrors body for other methods.

# GET shows request info (text/plain)
curl http://localhost:8080/
# GET / HTTP/1.1
# Host: localhost:8080
# ...

# POST mirrors body (content type preserved unless overridden)
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"hello":"world"}'
# {"hello":"world"}

GET /health

Health check endpoint - returns server status and basic metrics.

curl http://localhost:8080/health
# {"status":"healthy","timestamp":"2025-01-01T00:00:00Z","uptime":"..."}

GET /ready

Readiness probe endpoint - returns readiness status (200 OK when ready).

curl http://localhost:8080/ready
# {"status":"ready"}

GET /info

Server info endpoint - returns request details and server metadata (hostname, version, uptime, request_id).

curl http://localhost:8080/info
# {
#   "method": "GET",
#   "path": "/info",
#   "remote_addr": "127.0.0.1",
#   "server": {"hostname": "...", "version": "1.0.0", "uptime": "..."}
# }

GET /metrics

Prometheus metrics endpoint - returns all collected metrics.

echo_requests_total{method,path,status}
echo_request_duration_seconds
echo_chaos_errors_total{type}

curl http://localhost:8080/metrics | head -n 10
# HELP echo_requests_total Total number of requests processed
# TYPE echo_requests_total counter
# echo_requests_total{method="GET",path="/",status="200"} 42

GET /ws

WebSocket upgrade endpoint - establishes WebSocket connection for real-time communication. UI at /web-ws.

GET /sse

Server-Sent Events endpoint - streams JSON events to connected clients. UI at /web-sse. Interval controlled by ECHO_SSE_TICKER.

Management Endpoints

GET /history

Retrieve stored request history.

POST /replay

Replay a specific request by ID with optional modifications.

Body:
{
  "id": "65b4c414c94d3a00010c2c1a",
  "target": "https://external-api.example.com/endpoint"
}

GET /scenario

Get current scenarios configuration.

curl http://localhost:8080/scenario
# Output: [{"path": "/test", "responses": [{"status": 200, "delay": "100ms", "body": "OK"}]}]

POST /scenario

Update scenarios configuration with JSON array.

curl -X POST http://localhost:8080/scenario \
  -H "Content-Type: application/json" \
  -d '[{"path": "/test", "responses": [{"status": 200, "delay": "100ms"}, {"status": 500}]}]'
# Response: {"status": "scenarios updated"}

Request Headers

Header	Purpose	Example
`X-Echo-Delay`	Add simple delay (ms)	`500ms`
`X-Echo-Jitter`	Base ± jitter (ms, base,jitter)	`100,50`
`X-Echo-Random-Delay`	Random delay in range (ms,min,max)	`100,500`
`X-Echo-Exponential`	Exponential backoff (base_ms,attempt)	`100,3`
`X-Echo-Latency`	Latency injection (fixed or min-max)	`100ms` or `100-200ms`
`X-Echo-Status`	Set response status	`201`
`X-Echo-Error`	Simulate specific error	`timeout`, `503`, `random`
`X-Echo-Chaos`	Random error percentage (0-100)	`15`
`X-Echo-Response-Size`	Set response size in bytes (random data)	`1024`
`X-Echo-Compress`	Enable compression	`gzip`
`X-Echo-Content-Type`	Override response Content-Type	`application/xml`
`X-Echo-Set-Header-*`	Set arbitrary response header (dash-cased)	`X-Echo-Set-Header-X-App-Version: 1.2.3`
`X-Echo-Headers`	Echo listed request headers back as X-Echoed-*	`X-Correlation-ID`
`X-Echo-Server-Info`	Include server info headers	`true`