API Mock Server

---
name: api-mock-server
description: |
  Trigger when the user asks to mock an API, spin up a mock server, or
  generate fixtures from an OpenAPI spec. Phrases: "mock API", "mock server",
  "fake backend", "stub endpoints", "contract mock", "prism".
allowed-tools:
  - Read
  - Write
  - Bash(npx prism *)
  - Bash(npx msw *)
  - Bash(pnpm add *)
---

# API Mock Server

Stand up a realistic mock server so frontend, tests, and demos can run
without the real backend. Works from an OpenAPI spec, a Postman collection,
or hand-written handlers.

## Prerequisites

- OpenAPI / Swagger spec, or a clear list of endpoints to mock
- Decision on tool: Prism (spec-driven), MSW (browser + Node), or json-server
  (prototypes only)

## Steps

1. **Pick the right tool for the job:**
   - **Prism** - you have an OpenAPI spec and want response validation
   - **MSW** - you want mocks that run inside tests and in the browser
   - **json-server** - quick prototype, no spec, REST-only
   - **WireMock** - JVM shops, need record/replay of real traffic

2. **Spec-driven with Prism (recommended when a spec exists):**
   ```bash
   npx @stoplight/prism-cli mock openapi.yaml --port 4010 --dynamic
   ```
   `--dynamic` generates fake data from the schema. Without it you get
   the examples from the spec (more predictable, less varied).

3. **Test-scoped with MSW:**
   ```ts
   import { http, HttpResponse } from 'msw'
   import { setupServer } from 'msw/node'

   const server = setupServer(
     http.get('/api/users/:id', ({ params }) => {
       return HttpResponse.json({ id: params.id, name: 'Test User' })
     })
   )
   server.listen()
   ```

4. **Seed realistic data.** Random faker data is fine for smoke tests,
   but demos need believable names, dates, and relationships. Commit a
   fixtures file so mock responses are stable across runs.

5. **Simulate failure modes.** A mock that only returns 200s hides bugs.
   Add toggles for:
   - 500 errors on specific endpoints
   - Slow responses (500ms - 5s latency)
   - Timeouts
   - 401 / 403 for auth flows
   - Rate limit 429s

6. **Contract testing.** If the spec is the source of truth, wire Prism's
   proxy mode into CI so the real backend gets validated against the spec
   on every deploy:
   ```bash
   prism proxy openapi.yaml https://api.staging.example.com
   ```

## Patterns that work

- Mock server port matches a documented dev-only env var (e.g. `API_URL`)
- Fixtures live in `tests/fixtures/` and are versioned
- One command brings up the mock (`pnpm mock`)
- Same mocks used in frontend dev and in test suite (MSW gives you this)

## Anti-patterns

- Hand-rolled mocks that drift from the real API
- Mocks only in tests, not available for local dev
- No way to toggle failure scenarios
- Mock responses that always return the same id (masks caching bugs)

## Output

- Running mock server with documented port and endpoints
- Fixtures file for stable, realistic data
- Failure scenario toggles documented in README
- CI contract check (if spec-driven)