Documentation

Complete guide to setting up, configuring, and using OrchestAPI — the self-hosted API test orchestration platform with DAG-based dependencies, live streaming, infrastructure verification, and scheduled execution.

Prerequisites

• Java 21 (for running from source)
• Node.js 18+ with npm (for frontend development)
• PostgreSQL 14+ (or Docker to run it)
• Docker (recommended for production deployment)

Quick Start

1. Start PostgreSQL

Using Docker:

docker run -d \
  --name orchestapi-db \
  -e POSTGRES_USER=orchestapi \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=orchestapi \
  -p 5432:5432 \
  postgres:17

Or use any existing PostgreSQL instance.

2. Start the Backend

cd backend

# Set your database credentials
export DB_URL=jdbc:postgresql://localhost:5432/orchestapi
export DB_USERNAME=orchestapi
export DB_PASSWORD=your_password

# Run
./mvnw spring-boot:run

The backend starts on http://localhost:8080. Database schema and tables are created automatically via Flyway on first startup.

3. Start the Frontend

cd frontend
npm install
npm run dev

The frontend starts on http://localhost:3000 and proxies API calls to the backend.

Docker Deployment

The recommended way to deploy OrchestAPI in production is via Docker. The image bundles both frontend and backend into a single container.

Using Docker Compose (recommended)

# Clone the repository
git clone https://github.com/santhoshkumr96/orchestapi.git
cd orchestapi

# Start everything (PostgreSQL + OrchestAPI)
docker compose up -d

# Open http://localhost:8080

Using Docker directly

# Pull the image
docker pull santhoshkumr96/orchestapi:latest

# Run with your own PostgreSQL
docker run -d \
  --name orchestapi \
  -p 8080:8080 \
  -e DB_URL=jdbc:postgresql://your-host:5432/orchestapi \
  -e DB_USERNAME=orchestapi \
  -e DB_PASSWORD=your_password \
  santhoshkumr96/orchestapi:latest

Building the image locally

docker build -t santhoshkumr96/orchestapi:latest .

Environments

Environments hold all the configuration for a target system — variables, headers, infrastructure connectors, and files. Each test suite has a default environment, which can be overridden at run time.

Go to Environments in the sidebar, click New Environment, then configure the sections below.

Variables

Key-value pairs available to all steps via ${VAR_NAME} syntax.

Common variables: BASE_URL, API_KEY, AUTH_TOKEN, TENANT_ID.

Default Headers

Headers automatically added to every API step that uses this environment. Step-level headers override these if the same key is used.

Value Types

Connectors

Infrastructure connectors for post-step verifications (e.g., check a DB row was created, verify a Kafka event was published). See Connector Reference for all types and config fields.

Use the Test Connection button to verify connectivity before saving.

Files

Binary files stored in the database, referenced in form-data requests via ${FILE:fileKey}.

Test Suites

A test suite is a collection of API steps with an optional dependency graph (DAG). Go to Test Suites in the sidebar.

Steps within a suite can depend on each other, forming a directed acyclic graph. The execution engine resolves this graph and runs steps in the correct order.

Steps

Each step represents a single API call. Click + Add Step or use Import from curl to create one. The step editor has a familiar tabbed interface:

• Headers — request headers
• Params — query parameters
• Body — request body (JSON or form-data)
• Dependencies — step dependencies
• Handlers — response code handlers
• Variables — variable extraction
• Verifications — infrastructure verifications
• Validation — response validation rules

HTTP Methods

GET POST PUT DELETE PATCH

The URL supports placeholders: ${BASE_URL}/api/users/{{Create User.id}}

Headers

Step-level headers that override environment defaults when the same key is used. Each header is a key-value pair. Placeholders work in both key and value.

Request Body

Form Data Fields

Query Parameters

Key-value pairs appended to the URL as ?key=value&key2=value2. Placeholders supported in both key and value.

Dependencies

Steps that must execute before this one. Select from other steps in the same suite.

Once a dependency is added, reference its response data with {{StepName.jsonPath}} in any field.

Variable Extraction

Extract values from a step's response for use in later steps.

Extraction Sources

JSON Path Syntax

Response Handlers

Define what action to take for each HTTP status code. Handlers are evaluated in priority order. Specific codes take precedence over ranges.

Actions

Example Setup

Caching

Within-run response caching to avoid re-executing the same dependency multiple times.

Dependency-Only Steps

Use this for setup steps (e.g., "Create Auth Token") that should only run when another step depends on them.

Verifications (Infrastructure)

Run queries against infrastructure connectors after the API call completes, then assert on the results. Verify side effects like database rows, Kafka events, or Redis keys.

Pre-Listen Mode

For asynchronous systems where the event is published during the API call:

1. Verification sets up a listener (e.g., Kafka consumer) before the API call
2. Step executes the API call
3. Listener waits for a matching message within the timeout
4. Assertions run on the received message

Assertions

Each verification can have multiple assertions on the query result:

Response Validation

Validate the HTTP response itself (separate from infrastructure verifications). Four validation types are available:

1. Header Validation

Assert response headers match expected values. Useful for checking content types, cache headers, auth tokens.

2. Body Exact Match

Compare the entire response body against an expected payload.

3. Body Field Assertion

Target specific fields via JSON path and apply assertion operators.

4. Body Data Type

Verify field types at any JSON path.

Placeholders & Autocomplete

OrchestAPI supports four types of dynamic placeholders. All placeholder-enabled fields show an autocomplete dropdown.

Environment Variables — ${VAR_NAME}

Type ${ to trigger autocomplete. Resolves to the variable value from the active environment. Works in URL, headers, body, query params, and verification queries.

Step Response References — {{StepName.path}}

Type {{ to trigger autocomplete. References extracted variables or any JSON path from a dependency step's response. Two-step autocomplete:

1. Type {{ → shows dependent step names
2. Select a step → type . → shows extracted variable names
3. You can also type a custom JSON path (e.g., {{StepName.data.items[0].id}})

Manual Input — #{paramName}

During execution, the UI pauses and shows an input modal. Enter the value and execution resumes.

File References — ${FILE:fileKey}

Type ${FILE: to trigger autocomplete. References an uploaded file from the environment's Files section. Used in form-data fields to attach files to multipart requests.

Running Tests

Single Step

Click the play button next to any step. The step and all its transitive dependencies execute in order. Results show the target step at top level with dependencies in a collapsible accordion.

Full Suite

Click Run Suite at the top of the suite detail page. Optionally override the default environment. All non-dependency-only steps execute in topological order based on the dependency graph.

Live Streaming (SSE)

Both single step and suite runs stream results in real time via Server-Sent Events:

Manual Input During Runs

When a step contains #{param} placeholders, execution pauses and shows a modal. Each parameter is shown with its name, optional default, and cached value from earlier steps.

Run Results

Each step result includes:

Step Status Values

Suite Status Values

Scheduling

Go to Runs page → Schedules tab.

Create a Schedule

Cron Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Examples

Use Preview to see the next fire times before saving.

Run History

Go to Runs page → Run History tab.

Click any row to expand full step-by-step results. Export results to JSON.

Dashboard

The dashboard shows execution statistics at a glance:

• Total Runs — all runs ever executed
• Pass Rate — percentage of successful runs
• Active Schedules — number of enabled schedules
• Total Suites / Environments — entity counts
• Recent Runs — latest run results
• Suite Health — pass rate per suite

Mock Server

Create standalone mock API endpoints to simulate external services during testing. Go to Mock Server in the sidebar.

Mock Servers

Each mock server gets a unique URL: http://your-host/mock/{serverId}/...

Mock Endpoints

Each endpoint defines a path pattern, HTTP method, and configurable response.

Path Matching

Match Rules

All rules must match (AND logic). Endpoints are evaluated in sort order — first match wins.

Request Logging

All incoming requests are logged with method, path, headers, body, response status, duration, and whether an endpoint was matched.

Webhook Tester

Receive and inspect incoming HTTP requests in real-time — like webhook.site, but self-hosted. Go to Webhooks in the sidebar.

Creating a Webhook

Each webhook gets a unique URL: http://your-host/webhook/{webhookId}/...

Any HTTP method can be used. The webhook captures everything and returns the configured response.

Request Inspection

The detail page shows a two-panel layout:

• Left panel: Live list of incoming requests (method, path, source IP, timestamp)
• Right panel: Full request detail for the selected request

Captured Data

File Handling

Real-Time Streaming

The detail page connects via SSE and shows new requests instantly with a green “Live” indicator. Multiple browser tabs can monitor the same webhook simultaneously.

Limits

When a webhook is disabled, incoming requests receive a 503 Service Unavailable response.

Curl Import

Quickly create a step from a curl command. Click Import from curl in the suite detail page.

Supported Flags

Line continuations (\) are handled. Step name is auto-generated from the URL path. Method defaults to POST if body is present, GET otherwise.

Connector Reference

JDBC (MySQL, PostgreSQL, Oracle, SQL Server)

Query: Standard SQL SELECT statements.

Result: { "rows": [{ "id": 1, "name": "test" }], "rowCount": 1 }

Redis

Query: GET key, HGET hash field, HGETALL hash, EXISTS key, LRANGE key 0 -1, SISMEMBER set member.

Result: { "value": "data", "type": "string", "exists": true }

Elasticsearch

Query: METHOD /path body — e.g., GET /my-index/_search {"query":{"match_all":{}}}

Kafka

Query (newline-separated):

topic=events_topic
key=order-123

Creates an isolated consumer group per verification (UUID-based). Seeks to latest offset and waits for new messages.

Result: { "found": true, "key": "order-123",
  "value": { "eventType": "ORDER_CREATED" },
  "partition": 0, "offset": 42 }

RabbitMQ

Query (space-separated): queue=my_queue routingKey=order.created

Result: { "found": true, "routingKey": "order.created",
  "body": { "orderId": "123" }, "headers": {} }

MongoDB

Option A: connectionString — full MongoDB URI.

Option B: Individual fields — host, port, database, username, password.

Query: collection.{filter_json} — e.g., orders.{"orderId":"abc123"}

Result: { "documents": [{ "orderId": "abc123", "status": "completed" }], "count": 1 }

Deployment

Context Path (Reverse Proxy / Kubernetes)

When deploying behind a reverse proxy or Kubernetes Ingress with a path prefix (e.g., https://company.com/orchestapi), set two environment variables:

VITE_BASE_PATH is a Docker build argument (compiled into the frontend at build time), while CONTEXT_PATH is a runtime environment variable. Both must have the same value.

# Build with custom base path
docker build --build-arg VITE_BASE_PATH=/orchestapi -t orchestapi .

# Run with context path
docker run -d \
  --name orchestapi \
  -p 8080:8080 \
  -e CONTEXT_PATH=/orchestapi \
  -e DB_URL=jdbc:postgresql://db:5432/orchestapi \
  -e DB_USERNAME=orchestapi \
  -e DB_PASSWORD=your_password \
  orchestapi

Nginx Reverse Proxy

location /orchestapi/ {
    proxy_pass http://orchestapi:8080/orchestapi/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: orchestapi
spec:
  rules:
    - host: company.com
      http:
        paths:
          - path: /orchestapi
            pathType: Prefix
            backend:
              service:
                name: orchestapi
                port:
                  number: 8080

Configuration

Server Environment Variables

Limits

Database

• Schema: orchestrator (auto-created by Flyway)
• All tables prefixed with orchestapi_
• Flyway history table: orchestapi_flyway_history
• Migrations run automatically on startup