PROJECT-CONTORL/openspec/changes/update-api-consistency/design.md

Context

The current API behavior is functionally correct but has ambiguities that cause client confusion: WebSocket handshake messaging differs from inline docs, 409 conflict responses are inconsistent for clients, and workload heatmap defaults vary based on calendar edge cases (Sunday).

Goals / Non-Goals

• Goals:
  • Make WebSocket auth expectations explicit and consistent.
  • Provide a stable, machine-readable conflict response for optimistic locking.
  • Define predictable workload heatmap defaults and edge-case handling.
• Non-Goals:
  • Full API version migration (/api to /api/v1).
  • Redesign of workload UI or heatmap visualization.

Decisions

• WebSocket auth handshake: keep first-message authentication; do not require a pre-auth banner. Add explicit invalid-token error message prior to close.
• Optimistic locking: return a standardized 409 payload containing a human-readable message plus current/provided version fields.
• Workload defaults: show all accessible users by default (including zero workload); support hide_empty=true to exclude them. When week_start is omitted and today is Sunday, extend the default week window to include the upcoming week to avoid empty default views.
• Caching: include hide_empty in cache key and cache the default path to keep latency stable.

Risks / Trade-offs

• Returning more users by default may increase response sizes; cache should offset this.
• Sunday window extension changes semantics of "current week"; clients must understand the rule.
• Conflict payload change may require frontend updates if it expects a string-only detail.

Migration Plan

• Update specs first, then implement backend changes.
• Update frontend only if new defaults or conflict payloads require parsing changes.
• Add regression tests for WebSocket auth invalid token, conflict payload shape, and heatmap defaults.

Open Questions

• Should we add an explicit auth_required message before waiting for the auth payload (client UX improvement), or keep the minimal handshake?