api-mock

name: api-mock description: Serve fake API responses from a YAML definition file with Faker.js data and configurable latency. Use when you need to develop a frontend without a backend, test error states, simulate slow APIs, or do contract-first API development. Triggers include "mock API", "fake backend", "stub API", "YAML mock server", "frontend without backend", "simulate API", "API contract testing".

Serve realistic fake API responses from a YAML file. Hot reloads on file change. Web dashboard included.

When to use

Frontend development without a backend
Testing error states and edge cases (404, 500, payment declined)
Contract-first API development (define the API shape, build against it)
Demos that need realistic data
CI/CD tests that need a predictable API

Installation

npm install -g @your-org/api-mock-server

Quick Start

# Create api-mock.yaml
cat > api-mock.yaml << 'EOF'
endpoints:
  - method: GET
    path: /api/users
    status: 200
    body:
      users:
        - id: "{{faker.string.uuid}}"
          name: "{{faker.person.fullName}}"
          email: "{{faker.internet.email}}"
EOF

# Start the server
api-mock start
# Server: http://127.0.0.1:3100
# Dashboard: http://127.0.0.1:3101

YAML Schema

endpoints:
  - method: GET              # HTTP method
    path: /api/users/:id     # Path (Express-style params)
    status: 200              # Response status code
    latency: 50              # Delay in ms (default: 0)
    headers:
      Content-Type: application/json
    body:
      id: "{{params.id}}"
      name: "{{faker.person.fullName}}"
    scenarios:
      - name: not-found
        status: 404
        body:
          error: "Not found"

Faker Templates

Template	Example output
`{{faker.string.uuid}}`	`550e8400-e29b-41d4-a716-...`
`{{faker.person.fullName}}`	`Alice Johnson`
`{{faker.internet.email}}`	`alice@example.com`
`{{faker.date.recent}}`	`2025-01-10T14:33:00.000Z`
`{{faker.commerce.price}}`	`49.99`
`{{faker.number.int min=1 max=100}}`	`42`
`{{params.id}}`	URL param value
`{{body.fieldName}}`	Request body field
`{{query.page}}`	Query string value

Scenario Activation

# Persistent (via dashboard or API)
curl -X POST http://127.0.0.1:3101/api/scenarios/GET%20%2Fapi%2Fusers%2F%3Aid \
  -H 'Content-Type: application/json' \
  -d '{"scenario": "not-found"}'

# Per-request (does not persist)
curl http://127.0.0.1:3100/api/users/42?__scenario=not-found

CLI Reference

Command	Description
`api-mock start [file]`	Start mock server (default: api-mock.yaml)
`api-mock start --port 3200`	Override mock server port
`api-mock start --dashboard 3201`	Override dashboard port
`api-mock start --latency 100`	Add global latency to all responses
`api-mock validate [file]`	Validate YAML without starting server
`api-mock --help`	Show help
`api-mock --version`	Show version

Environment Variables

Variable	Description	Default
`MOCK_PORT`	Mock server port	`3100`
`MOCK_DASHBOARD_PORT`	Dashboard port	`3101`
`MOCK_CONFIG`	Path to YAML config	`api-mock.yaml`
`MOCK_LATENCY`	Global latency in ms	`0`
`MOCK_LOG_RETENTION`	Request log retention days	`3`
`MOCK_ALLOW_REMOTE`	Allow remote connections (0 or 1)	`0`

Troubleshooting

"config file not found"

Create api-mock.yaml in the current directory, or pass the path: api-mock start path/to/config.yaml.

Template rendered as literal string

Check that template syntax uses double curly braces: {{faker.string.uuid}}. Single braces or backtick-style won't be recognized.

Endpoint returns 404 with "no mock defined"

The path doesn't match any defined endpoint. Check the method and path pattern in your YAML. Use :param for dynamic segments.