synthetic-api

synthetic-api

A declarative mock backend CLI for frontend developers.

You define API routes in JSON, then run a local or cloud-hosted mock API with:

• REST methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• optional auth (none, bearer, apiKey)
• request validation (querySchema, bodySchema, headersSchema)
• simulated errors and latency
• offset/cursor pagination
• configurable CORS

Quick Start (New Project)

mkdir my-mock-api && cd my-mock-api
npx synthetic-api init
npm install
npm run start

Then call:

• GET http://localhost:4010/
• GET http://localhost:4010/health
• GET http://localhost:4010/__routes

init scaffolds:

• synthetic-api.config.json
• fixtures/users.json
• deploy files: Dockerfile, .dockerignore, render.yaml, railway.json, Procfile
• package.json scripts: start, dev, validate, start:cloud, help

Behavior:

• Existing files are skipped by default.
• Use --force to overwrite generated files/scripts.
• If you use --config <path>, generated npm scripts use that same config path.

Install Modes

Run without installing:

npx synthetic-api --help

Install in a project:

npm i synthetic-api
npx synthetic-api init

Install globally:

npm i -g synthetic-api
synthetic-api --help

CLI

synthetic-api init [--config synthetic-api.config.json] [--force]
synthetic-api dev [--config synthetic-api.config.json] [--port 4010] [--watch true|false]
synthetic-api validate [--config synthetic-api.config.json]
synthetic-api tunnel [--port 4010] [--provider auto|cloudflared|ngrok]

Port resolution order for dev:

• --port
• PORT environment variable
• 4010

Built-in Endpoints

• GET /health: healthcheck payload (for cloud probes)
• GET /__routes: routes index (includes system + declared routes)

Config Example

{
  "version": 1,
  "global": {
    "latencyMs": [50, 250],
    "cors": {
      "enabled": true,
      "origin": "*",
      "methods": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
      "headers": ["content-type", "authorization", "x-api-key"]
    }
  },
  "auth": {
    "tokens": ["demo-token"],
    "apiKeys": ["demo-key"]
  },
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "querySchema": { "page": "number?", "limit": "number?" },
      "pagination": { "type": "offset", "defaultLimit": 5 },
      "response": { "status": 200, "bodyFrom": "fixtures/users.json" },
      "errors": [{ "status": 500, "probability": 0.05 }]
    }
  ]
}

Template variables in response strings:

• {{params.id}}
• {{query.page}}
• {{body.email}}

Cloud Deploy

Use:

npm run start:cloud

start:cloud:

• disables file watching
• reads PORT from host environment

Scaffold includes provider files:

• render.yaml
• railway.json
• Procfile
• Dockerfile