Files
HealthLog/docs/api/README.md
T
Marc-André Bombeck 7c40ba8202 feat(nutrients): accept measurements:write tokens on the nutrient batch
A bridge such as a food tracker can now post daily nutrient totals with
the measurement token. The credential picks the source row: a scoped
token writes EXTERNAL, the native client keeps writing APPLE_HEALTH, and
the body has no say. Bridge tokens count in their own rate-limit bucket,
and the source is recorded in the audit row.

The write phase moves into writeNutrientDayTotals so the route keeps
only parsing, validation and bookkeeping. The scope guard now freezes
four doors for measurements:write. Refs #1402.
2026-11-17 18:47:11 +01:00

126 lines
5.8 KiB
Markdown

# HealthLog API Spec
`openapi.yaml` is the OpenAPI 3.1 description for the HealthLog
Next.js API and the source of truth for the native iOS client's DTO
codegen. The file is **generated**: `pnpm openapi:generate` emits it
from the Zod registry under `src/lib/openapi/` (`registry.ts` plus the
route modules in `src/lib/openapi/routes/`). Do not edit the YAML by
hand; the next generation overwrites it, and CI (`openapi:check`)
fails the build when the committed YAML drifts from the registry.
The MCP server is documented separately — it is a distinct contract over
JSON-RPC, not part of the REST OpenAPI spec:
- [`mcp-capabilities.md`](./mcp-capabilities.md) — the tool, resource, and
prompt catalogue, the grounding contract, and the write model.
- [`mcp-skills.md`](./mcp-skills.md) — building a connector or skill on
top of it.
- [`../self-hosting/mcp.md`](../self-hosting/mcp.md) — enabling and
connecting the surface (operator guide).
## Preview locally
Open an interactive Redoc preview in your browser:
```bash
npx @redocly/cli preview docs/api/openapi.yaml
```
Generate static HTML for sharing:
```bash
npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
```
## Validate
```bash
npx @redocly/cli lint docs/api/openapi.yaml
```
The spec is expected to be lint-clean (errors = 0). Warnings such as
`no-server-example.com` for the localhost dev server are tolerated;
re-run the lint to see what it produces against the current file
before treating a warning as a regression.
## Layout
- **`info`** — title, description, and `version` mirrored automatically
from `package.json` at generation time. Never bump it by hand.
- **`servers`** — `https://healthlog.example.com` as the self-hosted
placeholder plus `http://localhost:3000` for local development.
- **`tags`** — domain groupings; the current set lives at the top of
the generated file (`Auth`, `Measurements`, `Medications`, `Mood`,
`Analytics`, `Insights`, `Consent`, `Dashboard`, `Notifications`,
`Devices`, `Export`, `Sync`, `Cycle`, `MeasurementReminders`,
`Labs`, `Illness`, `Documents`, `Records`, `Admin`, `Meta`,
`Retired`).
- **`securitySchemes`**:
- `bearerAuth` — `hlk_*` API tokens. A scope grants what it names and
nothing adjacent, so where a token comes from decides what it reaches:
- a completed password / passkey / refresh exchange mints the
cookie-equivalent `["*"]` token the native client carries;
- a medication's own API-endpoint toggle mints `medication:ingest` plus
`medication:<id>:ingest`, the pair `/api/ingest/medication` gates on;
- `POST /api/mcp/tokens` mints `health:read` (optionally plus
`health:write`), audience-bound to `/mcp` and refused on REST writes;
- `POST /api/tokens/measurements` mints `measurements:write`, accepted by
`POST /api/measurements`, `POST /api/measurements/batch`,
`POST /api/custom-metrics/{id}/entries` and `POST /api/nutrients/batch`
only, on the holder's own record only. The readings and nutrient day
totals it writes carry `source: EXTERNAL`
and are linked to the token; whether the HealthLog app writes them into
Apple Health is the token's `mirrorToAppleHealth` setting (off by
default, changed with `PATCH /api/tokens/{id}`), resolved onto every
measurement row as `appleHealthMirror`;
- `POST /api/tokens/workouts` mints `workouts:write`, accepted by
`POST /api/workouts/batch` only, on the holder's own record only; the
workouts it writes carry `source: EXTERNAL`;
- `POST /api/tokens/documents` mints `documents:write`, accepted by
`POST /api/documents/inbound` and `GET /api/documents/inbound/source`
only.
`POST /api/tokens` is **not** among them — that generic mint was removed in
v1.30.17. The path still lists (`GET`) and revokes (`DELETE /api/tokens/{id}`)
every token above, whichever surface issued it.
- `sessionCookie` — HttpOnly session cookie set by the password and
passkey login flows. Used by the web app and any iOS client running
inside a web view. It is named `__Host-healthlog_session` wherever it is
`Secure` (every HTTPS install), so no other host under the same domain
can set it; a plain-HTTP install keeps `healthlog_session`. A cookie
under the old name is still read and is re-issued under the new one.
- **`components.schemas`** — DTOs for the documented routes plus the
underlying Prisma models (e.g. `Measurement`, `Medication`,
`MedicationIntakeEvent`, `MoodEntry`, `User`, `DashboardLayout`,
`ApiEnvelope`, `ApiError`).
- **`paths`** — the client-facing REST surface. Not every
`src/app/api/**/route.ts` is in the contract: most `/api/admin/*`
routes, the OAuth connect/callback legs, and the webhook surfaces
are not documented here. The `Retired` tag lists removed paths that
answer `410 Gone`.
## Conventions
- Successful responses use the envelope `{ data, error: null }`.
- Error responses use the envelope `{ data: null, error: '<message>' }`.
- Pagination uses `limit` + `offset` query parameters and a
`meta: { total, limit, offset }` block on the response.
- All timestamps are ISO 8601 / RFC 3339 (`format: date-time`) in UTC.
- IDs are CUIDs (opaque strings).
## Updating the spec
When adding or changing routes:
1. Update the relevant route handler under `src/app/api/**/route.ts`.
2. Change the Zod schemas and their `.meta()` registrations under
`src/lib/openapi/` (registry entry plus the matching module in
`src/lib/openapi/routes/`). Keep `operationId` camelCase and
stable; the iOS codegen keys off it.
3. Run `pnpm openapi:generate` and commit the regenerated
`openapi.yaml` alongside the schema change. CI's `openapi:check`
fails on drift.
4. Never edit the YAML directly and never bump `info.version` by
hand; the version follows `package.json` at generation time.