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".

api-mock

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}}	[e-mail]
{{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.