# Local API demos (offline)

The Concorde doc site does not call fragile third-party APIs during `yarn dev`. A **Service Worker** and the Vite dev middleware serve **`/docs-mock-api/*`** on the same origin.

## How it works

1. On load, `registerDocsMockApiServiceWorker()` registers `/docs-mock-api-sw.js`.
2. Requests to `/docs-mock-api/...` are handled by the SW (production build) or Vite middleware (dev).
3. Live examples use `serviceURL="/docs-mock-api"` and relative paths.

TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `DOCS_MOCK_GEO_SERVICE`, …).

## Routes

| Path | Used in |
|------|---------|
| `/docs-mock-api/api/users` | [My first component](/docs/getting-started/my-first-component) users list |
| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
| `/docs-mock-api/api/space-cats` | Fixtures shared with the jsonata unit tests |
| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
| `/docs-mock-api/api/market-order` | Fixtures shared with the jsonata unit tests |
| `POST /docs-mock-api/api/register` | **sonic-submit** — JSON, `multipart/form-data` (`sendAsFormData`), or `application/x-www-form-urlencoded` (native `<form>`); response includes parsed `email` + `token` |
| `POST /docs-mock-api/api/register/nested` | Wrapped body `{ data: { id, token } }` for the `submitResultKey` demo |
| `GET /docs-mock-api/api/register/echo` | Echoes query string (`method="get"` on submit) |
| `GET /docs-mock-api/auth/token` | [API configuration](/docs/misc/api-configuration) — tokenProvider (Basic or `eventsApiToken`) |
| `GET /docs-mock-api/api/config/protected` | Bearer / Basic; `docs-mock-stale-token` → **498** |
| `GET /docs-mock-api/wording/labels` | Wording batch (`labels[]`, `lang`) |
| `/docs-mock-api/geo/communes` | `@get` demos |
| `GET /docs-mock-api/flights` | Flight board (`key="flights"`): `sonic-list` · `sonic-fetch` · `sonic-queue` · `sonic-jsonata` · `sonic-states` and the input / select / radio / switch filter demos |

### Filters `GET /flights`

| Query | Meaning |
|-------|---------|
| `direction` | `departures` · `arrivals` |
| `q` | Substring on flight number, city or airport code |
| `status` | Comma-separated statuses to keep: `on-time` · `boarding` · `delayed` · `landed` · `cancelled` (`all` = no filter) |
| `offset` + `limit` | Pagination for **sonic-queue** lazy load |

### Pagination `GET /api/users`

| Query | Meaning |
|-------|---------|
| `offset` + `per_page` | Index-based slice on the filtered set — **sonic-queue** (`offset=$offset&per_page=$limit`) |
| `page` + `per_page` | 1-based page — static fetch examples (`?page=2`) |
| `limit` | Alias of `per_page` |
| `q` | Search on first name, last name, email (optional; **sonic-queue** + `dataFilterProvider`, field `name="q"`) |

**ALTCHA** (`sonic-captcha`) is **not** mocked — it still uses the Supersoniks service.

In TypeScript demos, import from `src/docs/mock-api/urls.ts` (e.g. `DOCS_MOCK_REQRES_SERVICE` on `serviceURL`).

## Source files

- `src/docs/mock-api/` — router, fixtures, service worker, `urls.ts`
- `scripts/docs-mock-api-vite-plugin.ts` — SW build + middleware
- `public/docs-mock-api-sw.js` — generated on `yarn dev` / `yarn build-docs`

```bash
yarn dev          # mock API on by default
yarn build-docs   # includes SW bundle
```