egg/PROJECT-CONTORL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35c90fe76b3d383ec65f7ff6d15beb4376345ad5
PROJECT-CONTORL/openspec/changes/archive/2026-01-11-update-api-consistency/design.md
beabigegg df50d5e7f8 chore: archive remaining OpenSpec proposals 
Archived proposals:
- add-trigger-conditions-weekly-subscription: Trigger conditions and weekly subscription
- update-api-consistency: WebSocket auth, optimistic locking, workload defaults

All implementations were already complete in previous commits (f5f870d).
Updated tasks.md with implementation summary.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 18:47:14 +08:00

2.0 KiB
Raw Blame History

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?