jackboxpartypack-gamepicker/docs/plans/2026-03-15-api-documentation-design.md

API Documentation Design

Date: 2026-03-15 Status: Approved

Goal

Create comprehensive, accurate API documentation for the Jackbox Game Picker by reading the source code directly — not relying on existing docs which may be stale or incorrect. The documentation serves both internal maintainers and external integrators (bot developers, extension authors, etc.).

Scope

• All 41 REST/HTTP endpoints across 7 route groups (Auth, Games, Sessions, Picker, Stats, Votes, Webhooks) plus the health check
• WebSocket protocol at /api/sessions/live (auth, subscriptions, event broadcasting)
• Does NOT cover: Chrome extension internals, deployment/Docker setup, frontend

Approach

OpenAPI-first with generated Markdown (Approach A from brainstorming).

• openapi.yaml (OpenAPI 3.1) is the single source of truth for REST endpoints
• Human-readable Markdown endpoint docs are derived from the spec and enriched with guide-style prose, curl examples, and workflow explanations
• WebSocket protocol documented separately in Markdown (outside OpenAPI's scope)
• Existing docs/ files archived to docs/archive/

File Structure

docs/
├── archive/                          # Old docs preserved here
│   ├── API_QUICK_REFERENCE.md
│   ├── BOT_INTEGRATION.md
│   ├── SESSION_END_QUICK_START.md
│   ├── SESSION_END_WEBSOCKET.md
│   ├── SESSION_START_WEBSOCKET.md
│   ├── WEBSOCKET_FLOW_DIAGRAM.md
│   ├── WEBSOCKET_SUBSCRIPTION_GUIDE.md
│   ├── WEBSOCKET_TESTING.md
│   └── todos.md
├── api/
│   ├── openapi.yaml                  # OpenAPI 3.1 spec (source of truth)
│   ├── README.md                     # API overview, auth, base URL, error conventions
│   ├── endpoints/
│   │   ├── auth.md
│   │   ├── games.md
│   │   ├── sessions.md
│   │   ├── picker.md
│   │   ├── stats.md
│   │   ├── votes.md
│   │   └── webhooks.md
│   ├── websocket.md                  # WebSocket protocol documentation
│   └── guides/
│       ├── getting-started.md        # Quick start: auth, pick a game, run a session
│       ├── session-lifecycle.md      # Sessions end-to-end
│       ├── voting-and-popularity.md  # Chat import, live votes, popularity scoring
│       └── webhooks-and-events.md    # Webhooks + WS event system
└── plans/

OpenAPI Spec Design

Info & Servers

• Title: "Jackbox Game Picker API"
• Servers: local dev (http://localhost:5000), Docker proxy (http://localhost:3000/api)

Security

• bearerAuth scheme (JWT via Authorization: Bearer <token>)
• Applied per-operation; public endpoints explicitly marked

Tags

Auth, Games, Sessions, Picker, Stats, Votes, Webhooks

Schemas (components)

• Game, Session, SessionGame, Pack, PackMeta
• Webhook, WebhookLog
• ChatMessage, LiveVote
• Error (reusable error response)
• Enums: status (playing/played/skipped), vote_type (up/down), favor_bias (-1/0/1), drawing (only/exclude), length (short/medium/long)

Per-operation

Each path operation includes: operationId, summary, description, parameters, requestBody, responses (success + all documented error codes)

Markdown Endpoint Template

Each file in docs/api/endpoints/ follows:

1. Header: Resource overview, what it represents, common use cases
2. Summary table: Method | Path | Auth | Description
3. Per-endpoint sections:
   • Description and when to use it
   • Authentication requirement
   • Parameters table (Name | In | Type | Required | Description)
   • Request body (JSON schema with field descriptions)
   • Success response (JSON example with annotations)
   • Error responses table (Status | Body | When)
   • curl example + sample response

WebSocket Documentation Structure

docs/api/websocket.md covers:

• Connection URL and setup
• Authentication flow (send auth message with JWT)
• Client-to-server message types: auth, subscribe, unsubscribe, ping
• Server-to-client message types: auth_success, subscribed, unsubscribed, pong, session.started, game.added, session.ended, player-count.updated, error, auth_error
• Subscription model (per-session)
• Event payloads with full JSON examples
• Heartbeat/timeout (60s) and reconnection guidance
• Complete session lifecycle example

Guide Documents

Each guide uses narrative prose connecting endpoints into workflows:

• getting-started.md: Authenticate, browse games, pick a game, start a session — minimum viable integration path
• session-lifecycle.md: Create session → add games → track status → room codes → player counts → close session
• voting-and-popularity.md: How popularity_score, upvotes, downvotes work; chat import flow; live vote endpoint; how voting affects the picker
• webhooks-and-events.md: Create/manage webhooks, event types, delivery logs, relationship between webhook events and WebSocket events

Maintenance Strategy

• openapi.yaml is the source of truth for REST endpoints
• When endpoints change: update spec first, then update Markdown
• WebSocket and guide docs are maintained manually
• No build-time generation tooling — Markdown committed directly

Validation Plan

After writing, cross-reference:

1. Every route file in backend/routes/ against the spec — no endpoints missed
2. Request/response shapes against database schema (backend/database.js) and route handlers
3. Auth requirements against middleware usage in each route