mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 16:12:11 +00:00
docs(insights): document english tile-id contract + naming ADR
Regenerate `docs/api/openapi.yaml` so the `InsightsLayoutBody` enum carries the canonical English tile ids first, then the accepted-but-deprecated legacy German ids, with the normalisation + deprecation spelled out in the schema description. Add ADR 0001 fixing the convention — localised UI copy, English internal identifiers — and the non-breaking alias strategy. Add an iOS coordination note covering the new canonical ids, the continued acceptance of the legacy ids, and the recommended migration path.
This commit is contained in:
1 parent
607dd9e5df
commit
262a3ad70a
4 files changed
+214
-12
No files matched your search
@@ -0,0 +1,80 @@
|
||||
# v1.8.0 — server → iOS: Insights tile-id rename (non-breaking)
|
||||
|
||||
Date: 2026-05-31
|
||||
From: server
|
||||
To: iOS
|
||||
Status: informational — no action required to keep working; action recommended before a future major
|
||||
|
||||
## Summary
|
||||
|
||||
v1.8.0 renames the Insights tile ids (and the matching web route slugs) from
|
||||
German to English to make the identifier space consistent. **This is
|
||||
non-breaking for the iOS layout sync.** The `GET/PUT /api/insights/layout`
|
||||
endpoint keeps accepting the old German ids. You do not need to ship anything to
|
||||
stay working. When convenient, migrate to the canonical English ids.
|
||||
|
||||
## What changed
|
||||
|
||||
The canonical tile ids in `GET/PUT /api/insights/layout` are now English:
|
||||
|
||||
| Legacy (≤ v1.7.x) | Canonical (v1.8.0+) |
|
||||
|---|---|
|
||||
| `blutdruck` | `blood-pressure` |
|
||||
| `puls` | `pulse` |
|
||||
| `sauerstoff` | `oxygen` |
|
||||
| `koerpertemperatur` | `body-temperature` |
|
||||
| `gewicht` | `weight` |
|
||||
| `aktive-energie` | `active-energy` |
|
||||
| `schlaf` | `sleep` |
|
||||
| `ruhepuls` | `resting-pulse` |
|
||||
| `stimmung` | `mood` |
|
||||
| `medikamente` | `medications` |
|
||||
|
||||
`overview`, `bmi`, `hrv`, and `workouts` were already language-neutral and are
|
||||
unchanged.
|
||||
|
||||
## Why it does not break you
|
||||
|
||||
- **PUT still accepts the legacy German ids.** The server's validation enum is
|
||||
the union of the canonical English ids and the legacy German aliases, so a
|
||||
`PUT` carrying `blutdruck` / `puls` / … validates (no 422).
|
||||
- **The server normalises legacy → canonical on write.** A `PUT` with German ids
|
||||
persists the English equivalents. So after any save, the stored layout is
|
||||
canonical English regardless of what you sent.
|
||||
- **GET always returns canonical English ids.** A layout you persisted before
|
||||
v1.8.0 (German ids) is normalised on read — `GET` surfaces the English ids
|
||||
without forcing a re-`PUT`.
|
||||
- **Dedupe.** If a payload carries both a legacy and a canonical id for one tile,
|
||||
the server keeps a single canonical entry.
|
||||
|
||||
So the worst case for an un-migrated iOS build is: it keeps sending German ids,
|
||||
the server keeps accepting and normalising them, and on the next `GET` the app
|
||||
sees English ids it does not recognise in its local enum. If your client filters
|
||||
unknown tile ids defensively, that filter must learn the English ids — see
|
||||
below.
|
||||
|
||||
## What iOS should do (recommended, before a future major)
|
||||
|
||||
1. **Add the English ids to your tile-id enum / model** (keep the German ones as
|
||||
decode-only aliases if your decoder is strict, or just map both).
|
||||
2. **Send English ids on `PUT`.** Once your build is out, you stop relying on the
|
||||
server's alias acceptance.
|
||||
3. **Decode `GET` responses expecting English ids.** Because the server
|
||||
normalises on read, a current `GET` already returns English; an app that hard-
|
||||
filters to the old German enum would drop every tile. Decode the English ids
|
||||
before you rely on this endpoint in a v1.8.0+ environment.
|
||||
|
||||
## Deprecation timeline
|
||||
|
||||
The legacy German ids are accepted-but-deprecated. They will be **removed from
|
||||
the accepted input set in a future major version** once we confirm clients have
|
||||
migrated. No date is fixed yet; we will give notice through this channel before
|
||||
the removal. Until then, both id sets validate.
|
||||
|
||||
## References
|
||||
|
||||
- Contract: `docs/api/openapi.yaml` → `InsightsLayoutBody` (lists canonical +
|
||||
legacy ids, with the deprecation noted in the schema description).
|
||||
- Rationale: `docs/adr/0001-insights-naming-convention.md`.
|
||||
- Web route slugs got the same English rename with 301 redirects from the legacy
|
||||
German URLs; that is web-only and does not affect the iOS contract.
|
||||
Reference in new issue
Block a user