api-mock

# 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

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

## Quick Start

```bash
# 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

```yaml
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

```bash
# 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.