docs: comprehensive API documentation from source code
Replace existing docs with fresh documentation built entirely from source code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable Markdown with curl examples, response samples, and workflow guides. - OpenAPI 3.1 spec covering all 42 endpoints (validated against source) - 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks) - WebSocket protocol documentation (auth, subscriptions, 4 event types) - 4 guide documents (getting started, session lifecycle, voting, webhooks) - API README with overview, auth docs, and quick reference table - Old docs archived to docs/archive/ Made-with: Cursor
This commit is contained in:
cottongin
176
docs/api/README.md
Normal file
176
docs/api/README.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Jackbox Game Picker API
|
||||
|
||||
## Overview
|
||||
|
||||
The API manages Jackbox Party Pack games, runs gaming sessions, tracks popularity via voting, picks games with weighted random selection, and notifies external systems via webhooks and WebSocket.
|
||||
|
||||
## Base URL
|
||||
|
||||
| Environment | Base URL | Notes |
|
||||
|-------------|----------|-------|
|
||||
| Local development | `http://localhost:5000` | Backend direct |
|
||||
| Docker Compose | `http://localhost:3000/api` | Via Vite/Nginx proxy |
|
||||
|
||||
All REST endpoints are prefixed with `/api/` except `/health`.
|
||||
|
||||
## Authentication
|
||||
|
||||
1. **Login**: POST to `/api/auth/login` with JSON body:
|
||||
|
||||
```json
|
||||
{ "key": "<admin-key>" }
|
||||
```
|
||||
|
||||
Returns a JWT token.
|
||||
|
||||
2. **Authorization**: Include the token in requests:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
3. **Expiry**: Tokens expire in 24 hours.
|
||||
|
||||
### Public Endpoints (no auth required)
|
||||
|
||||
- `GET /api/games`
|
||||
- `GET /api/games/packs`
|
||||
- `GET /api/games/meta/packs`
|
||||
- `GET /api/games/{id}`
|
||||
- `GET /api/sessions`
|
||||
- `GET /api/sessions/active`
|
||||
- `GET /api/sessions/{id}`
|
||||
- `GET /api/sessions/{id}/games`
|
||||
- `GET /api/stats`
|
||||
- `POST /api/pick`
|
||||
- `GET /health`
|
||||
|
||||
All write and admin operations require authentication.
|
||||
|
||||
## Request/Response Format
|
||||
|
||||
- Request and response bodies use JSON. Set `Content-Type: application/json`.
|
||||
- **Exceptions**:
|
||||
- `GET /api/games/export/csv` returns `text/csv`
|
||||
- `GET /api/sessions/{id}/export` returns `text/plain` or `application/json` depending on `format` query param
|
||||
|
||||
## Error Handling
|
||||
|
||||
All errors return:
|
||||
|
||||
```json
|
||||
{ "error": "description" }
|
||||
```
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| 400 | Bad request / validation failure |
|
||||
| 401 | No token provided |
|
||||
| 403 | Invalid or expired token |
|
||||
| 404 | Not found |
|
||||
| 409 | Conflict (e.g. duplicate vote) |
|
||||
| 500 | Server error |
|
||||
|
||||
Global error handler may include additional detail:
|
||||
|
||||
```json
|
||||
{ "error": "Something went wrong!", "message": "<details>" }
|
||||
```
|
||||
|
||||
## Boolean Fields
|
||||
|
||||
SQLite stores booleans as integers (0/1). In request bodies, pass JavaScript booleans (`true`/`false`); the API converts them. In responses, expect `0`/`1` for game and session fields. **Exception**: `Webhook.enabled` returns a JavaScript boolean.
|
||||
|
||||
## Pagination
|
||||
|
||||
No pagination. All list endpoints return full result sets.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Health
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| GET | `/health` | No | Health check |
|
||||
|
||||
### Auth
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| POST | `/api/auth/login` | No | Authenticate with admin key |
|
||||
| POST | `/api/auth/verify` | Yes | Verify JWT token |
|
||||
|
||||
### Games
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| GET | `/api/games` | No | List games with optional filters |
|
||||
| POST | `/api/games` | Yes | Create a new game |
|
||||
| GET | `/api/games/packs` | No | List all packs |
|
||||
| GET | `/api/games/meta/packs` | No | List pack metadata |
|
||||
| GET | `/api/games/export/csv` | Yes | Export games as CSV |
|
||||
| POST | `/api/games/import/csv` | Yes | Import games from CSV |
|
||||
| PATCH | `/api/games/packs/{name}/favor` | Yes | Update pack favor bias |
|
||||
| PATCH | `/api/games/packs/{name}/toggle` | Yes | Enable or disable a pack |
|
||||
| GET | `/api/games/{id}` | No | Get a game by ID |
|
||||
| PUT | `/api/games/{id}` | Yes | Update a game |
|
||||
| DELETE | `/api/games/{id}` | Yes | Delete a game |
|
||||
| PATCH | `/api/games/{id}/toggle` | Yes | Toggle game enabled status |
|
||||
| PATCH | `/api/games/{id}/favor` | Yes | Update game favor bias |
|
||||
|
||||
### Sessions
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| GET | `/api/sessions` | No | List all sessions |
|
||||
| POST | `/api/sessions` | Yes | Create a new session |
|
||||
| GET | `/api/sessions/active` | No | Get the active session |
|
||||
| GET | `/api/sessions/{id}` | No | Get a session by ID |
|
||||
| DELETE | `/api/sessions/{id}` | Yes | Delete a session |
|
||||
| POST | `/api/sessions/{id}/close` | Yes | Close a session |
|
||||
| GET | `/api/sessions/{id}/games` | No | List games in a session |
|
||||
| POST | `/api/sessions/{id}/games` | Yes | Add a game to a session |
|
||||
| POST | `/api/sessions/{id}/chat-import` | Yes | Import chat log for vote processing |
|
||||
| GET | `/api/sessions/{id}/export` | Yes | Export session |
|
||||
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/status` | Yes | Update session game status |
|
||||
| DELETE | `/api/sessions/{sessionId}/games/{sessionGameId}` | Yes | Remove game from session |
|
||||
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/room-code` | Yes | Update room code for session game |
|
||||
| POST | `/api/sessions/{sessionId}/games/{sessionGameId}/start-player-check` | Yes | Start room monitor for player count |
|
||||
| POST | `/api/sessions/{sessionId}/games/{sessionGameId}/stop-player-check` | Yes | Stop room monitor |
|
||||
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/player-count` | Yes | Update player count for session game |
|
||||
|
||||
### Picker
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| POST | `/api/pick` | No | Pick a random game with optional filters |
|
||||
|
||||
### Stats
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| GET | `/api/stats` | No | Get aggregate statistics |
|
||||
|
||||
### Votes
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| POST | `/api/votes/live` | Yes | Record a live vote (up/down) |
|
||||
|
||||
### Webhooks
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| GET | `/api/webhooks` | Yes | List all webhooks |
|
||||
| POST | `/api/webhooks` | Yes | Create a webhook |
|
||||
| GET | `/api/webhooks/{id}` | Yes | Get a webhook by ID |
|
||||
| PATCH | `/api/webhooks/{id}` | Yes | Update a webhook |
|
||||
| DELETE | `/api/webhooks/{id}` | Yes | Delete a webhook |
|
||||
| POST | `/api/webhooks/test/{id}` | Yes | Send test webhook |
|
||||
| GET | `/api/webhooks/{id}/logs` | Yes | List webhook delivery logs |
|
||||
|
||||
## Documentation Links
|
||||
|
||||
- [OpenAPI Spec](openapi.yaml)
|
||||
- **Endpoint docs**: [Auth](endpoints/auth.md), [Games](endpoints/games.md), [Sessions](endpoints/sessions.md), [Picker](endpoints/picker.md), [Stats](endpoints/stats.md), [Votes](endpoints/votes.md), [Webhooks](endpoints/webhooks.md)
|
||||
- [WebSocket Protocol](websocket.md)
|
||||
- **Guides**: [Getting Started](guides/getting-started.md), [Session Lifecycle](guides/session-lifecycle.md), [Voting & Popularity](guides/voting-and-popularity.md), [Webhooks & Events](guides/webhooks-and-events.md)
|
||||
Reference in New Issue
Block a user