mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
930cb227eb
The screener POST hardcoded source=WEB and ignored any client-supplied externalId, so the native client could not tag provenance and an outbox replay beyond the 24h idempotency-key window minted duplicate administrations plus duplicate trend points. Accept an optional closed source enum (WEB|IOS, default WEB) and an optional bounded externalId, and persist both. Deduplicate on (userId, externalId) when present: the route returns the existing administration on replay, and a partial unique index over (user_id, external_id) WHERE external_id IS NOT NULL (migration 0221) backstops a concurrent insert race (P2002 resolved to the winner). The derived *_SCORE measurement keeps its stable per-assessment externalId, so dedup at the assessment level prevents duplicate trend points. Item answers stay encrypted and out of AI/MCP/export. Regenerate OpenAPI.
HealthLog API Spec
openapi.yaml is the canonical OpenAPI 3.1 description for the HealthLog
Next.js API. It is the source of truth for the native iOS client's
DTO codegen.
The MCP server is documented separately — it is a distinct contract over JSON-RPC, not part of the REST OpenAPI spec:
mcp-capabilities.md— the tool, resource, and prompt catalogue, the grounding contract, and the write model.mcp-skills.md— building a connector or skill on top of it.../self-hosting/mcp.md— enabling and connecting the surface (operator guide).
Preview locally
Open an interactive Redoc preview in your browser:
npx @redocly/cli preview docs/api/openapi.yaml
Generate static HTML for sharing:
npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
Validate
npx @redocly/cli lint docs/api/openapi.yaml
The spec is expected to be lint-clean (errors = 0). Some warnings are intentional:
no-server-example.com—http://localhost:3000is the dev server.operation-2xx-response/operation-4xx-response— webhook + redirect endpoints intentionally omit one or the other.no-unused-components—ReminderPhaseis exposed for client codegen even though no path response references it directly.
Layout
info— title, version (mirrored frompackage.json), description.servers— productionhttps://healthlog.bombeck.ioplushttp://localhost:3000for local development.tags— domain groupings (Auth,Measurements,Medications,Mood,Dashboard,Insights,Achievements,DoctorReport,Integrations,User,Tokens,Notifications,Onboarding,Health,Settings,Analytics,Export,AuditLog,Monitoring,Webhooks,Ingest,Admin).securitySchemes:bearerAuth— long-livedhlk_*API tokens issued viaPOST /api/tokens. Required on/api/ingest/medication.sessionCookie— HttpOnlyhealthlog_sessioncookie set by the password and passkey login flows. Used by the web app and any iOS client running inside a web view.
components.schemas— DTOs for all routes plus the underlying Prisma models (e.g.Measurement,Medication,MedicationIntakeEvent,MoodEntry,User,DashboardLayout,ApiEnvelope,ApiError).paths— all routes fromsrc/app/api/**/route.ts, including the/api/admin/*family which is taggedAdminand marked internal.
Conventions
- Successful responses use the envelope
{ data, error: null }. - Error responses use the envelope
{ data: null, error: '<message>' }. - Pagination uses
limit+offsetquery parameters and ameta: { 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:
- Update the relevant route handler under
src/app/api/**/route.ts. - Mirror the change in
openapi.yaml. KeepoperationIdcamelCase and stable — the iOS codegen keys off it. - Run
npx @redocly/cli lint docs/api/openapi.yamland resolve all errors. Warnings are tolerated when documented above. - Bump
info.versionif the change is breaking for clients.