📝 fix: plannings endpoints — document verified behavior, drop 404-on-empty gotcha #58

Merged

mat merged 1 commit from docs/plannings-endpoint-verified into main

2026-09-06 16:59:17 +00:00

mat commented

2026-09-06 16:52:59 +00:00

Owner

Re-verified live on 2026-09-06 with the probe account (1 site, 19 real devices, 13 device kinds) before touching the docs — both ROADMAP §1 claims about /api/plannings turned out to be wrong:

Findings

GET /api/plannings?deviceId={id} → 200 on all 19 devices (paginated; content empty for 17, one planning each for the washing machine & dishwasher). The claimed systematic 500 Internal error is not reproducible.
GET /api/plannings?siteId={id} → 200 paginated (no trailing slash). The trailing-slash variant /api/plannings/?siteId= → 404 No static resource api/plannings. — Spring's static-handler fallthrough. It 404s even for a site that has plannings, so the "404 on empty list" gotcha was a misdiagnosis.
Bonus: siteId appears ignored — bogus or absent id still returns the authenticated user's plannings.

Changes

docs/energy.comwatt.com/misc-endpoints.md — plannings section rewritten with the verified behaviour + dated correction notes (repo convention)
docs/energy.comwatt.com/README.md — dropped the misdiagnosed gotcha (gotchas list) and corrected the 404 row in the error conventions
ROADMAP.md — removed the two resolved §1 items

Docs-only, no code. Tests: 133 passed.

Follow-up (out of scope here): ROADMAP §2.5 still says "Do not offer the ?deviceId= variant (500)" — that premise is now known false; should be updated when the get_plannings() client method is designed.

Re-verified live on **2026-09-06** with the probe account (1 site, 19 real devices, 13 device kinds) before touching the docs — both ROADMAP §1 claims about `/api/plannings` turned out to be wrong: **Findings** - `GET /api/plannings?deviceId={id}` → **200 on all 19 devices** (paginated; `content` empty for 17, one planning each for the washing machine & dishwasher). The claimed systematic `500 Internal error` is **not reproducible**. - `GET /api/plannings?siteId={id}` → **200 paginated** (no trailing slash). The trailing-slash variant `/api/plannings/?siteId=` → **404 `No static resource api/plannings.`** — Spring's static-handler fallthrough. It 404s even for a site that **has** plannings, so the "404 on empty list" gotcha was a misdiagnosis. - Bonus: `siteId` appears **ignored** — bogus or absent id still returns the authenticated user's plannings. **Changes** - `docs/energy.comwatt.com/misc-endpoints.md` — plannings section rewritten with the verified behaviour + dated correction notes (repo convention) - `docs/energy.comwatt.com/README.md` — dropped the misdiagnosed gotcha (gotchas list) and corrected the 404 row in the error conventions - `ROADMAP.md` — removed the two resolved §1 items Docs-only, no code. Tests: 133 passed. **Follow-up (out of scope here):** ROADMAP §2.5 still says *"Do not offer the `?deviceId=` variant (500)"* — that premise is now known false; should be updated when the `get_plannings()` client method is designed.

mat added 1 commit

2026-09-06 16:52:59 +00:00

📝 fix: plannings endpoints — document verified behavior, drop 404-on-empty gotcha

Tests / forgejo-pytest (push) Successful in 43s

Details

Tests / forgejo-pytest (pull_request) Successful in 43s

Details

05d97a8608

Live re-verification on 2026-09-06 (19 devices, 13 kinds, probe account):
- GET /api/plannings?deviceId= → 200 everywhere; the claimed 500 is not
  reproducible
- GET /api/plannings?siteId= → 200 paginated without trailing slash; the
  slash variant 404s (No static resource) regardless of emptiness — the
  "404 on empty list" gotcha was a misdiagnosis
- siteId appears ignored (bogus/absent id returns the user's plannings)

Resolves ROADMAP items §1 (plannings 500 + trailing-slash).

mat changed title from ~~WIP: 📝 fix: plannings endpoints — document verified behavior, drop 404-on-empty gotcha~~ to 📝 fix: plannings endpoints — document verified behavior, drop 404-on-empty gotcha

2026-09-06 16:57:14 +00:00

mat force-pushed docs/plannings-endpoint-verified from 05d97a8608

Tests / forgejo-pytest (push) Successful in 43s

Details

Tests / forgejo-pytest (pull_request) Successful in 43s

Details

to 26dcc6c374

Tests / forgejo-pytest (push) Successful in 53s

Details

Tests / forgejo-pytest (pull_request) Successful in 49s

Details

2026-09-06 16:58:43 +00:00