Skip to content

API — Approvals & publish

Purpose

Publishing a locked roster into an immutable published snapshot, the published-roster read surface, and the roster-approval queue.

Auth & roles

Area Base Gate
Roster publish /api/admin/roster roster.publish (SYS_ADMIN + PLANNER + MANAGER)
Roster approvals /api/admin/roster-approvals roster.approve (SYS_ADMIN + MANAGER)
Published rosters /api/admin/published-rosters roster.view

Endpoints

Publish — /api/admin/roster

Method Path Purpose
POST /api/admin/roster/publish Publish a locked roster
POST /api/admin/roster/republish Re-publish

Approvals — /api/admin/roster-approvals

Method Path Purpose
GET /api/admin/roster-approvals/pending · /pending/count Approval queue + bell count
POST /api/admin/roster-approvals/{id}/approve · /reject Approve / reject

Published rosters — /api/admin/published-rosters

Method Path Purpose
GET /api/admin/published-rosters · /{id} List / read published snapshots

Shapes & errors

Publishing materializes an immutable published snapshot (published_rosters + published_roster_lines); the queue exposes a pending count for the notification bell (sheet 10). Standard ProblemDetails.

Gotchas

  • The Approved waypoint is dead — publish goes straight to Published. The published-roster status enum defines an Approved = 3 value, but no code path routes through it: a publish transitions directly to Published. Treat Approved as a defined-but-unused state; don't write logic expecting a roster to sit in it.
  • Single-step publish/approve only. A multi-step approval chain, and a publisher≠approver separation, are PLANNED (sheet 10) — the current flow is single-step.
  • The bell is a frontend poll of the pending-count endpoints (every 30s); there is no backend push/notification system (sheet 18).
  • Published snapshots are immutable — corrections go through republish, not edits to the snapshot.