Business API contract

Rules

Base path /api/v1 and JSON unless streaming media/export.
HTTPS only in production.
Strict request/response schemas and bounded bodies.
Stable opaque IDs, ISO-8601 UTC timestamps, explicit canonical units.
Cursor pagination, not unbounded lists.
Idempotency-Key for retriable creation/mutation and sync batches.
Consistent error envelope: code, localized-safe message, request_id, optional field details; no internal stack data.
Frontends never send PocketBase filters, collection names, admin tokens, or generic record operations.

Initial endpoint families

POST   /auth/login
POST   /auth/totp/verify
POST   /auth/passkey/options
POST   /auth/passkey/verify
POST   /auth/refresh
POST   /auth/logout
POST   /auth/recover

GET    /me
PATCH  /me
DELETE /me
GET    /me/sessions
DELETE /me/sessions/{id}
GET    /me/devices
POST   /me/devices/pairing
DELETE /me/devices/{id}
GET    /me/passkeys
POST   /me/passkeys
DELETE /me/passkeys/{id}

POST   /sync/push
GET    /sync/pull?cursor=...

GET    /measurement-sessions
POST   /measurement-sessions
GET    /measurement-sessions/{id}
PATCH  /measurement-sessions/{id}
DELETE /measurement-sessions/{id}

GET    /workouts
GET    /sleep
GET    /heart-rate
GET    /activity-summaries

POST   /media/progress-photos
GET    /media/{id}
DELETE /media/{id}
POST   /avatar
DELETE /avatar

POST   /exports
GET    /exports/{id}
GET    /exports/{id}/download

GET    /references/version
GET    /references/exercises
GET    /references/foods

POST   /admin/invitations
GET    /admin/users
PATCH  /admin/users/{id}/status
GET    /admin/settings
PATCH  /admin/settings
POST   /admin/backups
POST   /admin/restores
POST   /admin/encryption-key/change
GET    /admin/audit

This is a contract outline, not permission to implement all endpoints before domain models and OpenAPI schemas are reviewed.

Authorization

User routes infer the principal and ownership. Admin routes authorize operational capabilities only. There is deliberately no admin endpoint for reading another user's health datasets or private media. Support actions revoke/reset access rather than impersonate.

Media

Uploads use streaming multipart with pre-decode and post-decode limits. Downloads authorize before opening/decrypting, support safe bounded streaming/ranges only if encryption format permits, and emit private/no-store cache headers.

Sync responses

Return per-operation status (accepted, duplicate, conflict, invalid, forbidden, retryable) and authoritative object version. One bad item does not ambiguously fail an entire batch; transactional group semantics must be explicit.

OpenAPI

Maintain a checked-in OpenAPI document as executable API documentation once implementation starts. Generate clients only when generated code is reviewed and does not leak transport models into domain layers. Contract tests verify server and Flutter clients against examples and error cases.

2.9 KiB Raw Blame History