Raj Nandan Sharma
35817bc20a
The public /maintenances/<id> route is keyed by maintenance EVENT id by default, while /api/v4/maintenances returns maintenance ids. Consumers that concatenated API ids onto the public path landed on the wrong page (#723) — an apparent off-by-one title mismatch with no actual data corruption. Instead of flipping the route default (which would break every internal link, subscriber email, and bookmarked URL), v4 API responses now carry an absolute `url` field built from the configured Site URL: - Maintenance responses link via /maintenances/<id>?type=maintenance - Maintenance event responses link via /maintenances/<event_id> - Incident responses link via /incidents/<id> (parity) Also updates the OpenAPI spec, records the decision in docs/adr/0002, and pins Maintenance vs Maintenance Event in CONTEXT.md. Fixes #723 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1.0 KiB
Public maintenance page is keyed by Maintenance Event id
The public route /maintenances/<id> interprets <id> as a Maintenance Event id by default (with ?type=maintenance to address a Maintenance definition instead), even though the route param is named maintenance_id. Issue #723 showed this misleads API consumers: /api/v4/maintenances returns Maintenance ids, and linking those to /maintenances/<id> lands on whatever Event happens to carry that id — an apparent "off-by-one title mismatch" with no actual data corruption.
We considered flipping the route default to Maintenance ids but rejected it: every internal status-page link, subscriber email, and externally bookmarked URL is keyed by Event id, and all of those would break. Instead, v4 API responses carry an absolute url field (built from the configured Site URL) that resolves correctly — ?type=maintenance for Maintenance objects, the plain Event-id path for Maintenance Events. Consumers should link via url, never by concatenating ids onto paths.