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
120
docs/api/endpoints/picker.md
Normal file
120
docs/api/endpoints/picker.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Picker Endpoints
|
||||
|
||||
Weighted random game selection. Picks from enabled games matching your filters, with favor bias affecting probability. Avoids recently played games within a session.
|
||||
|
||||
## Endpoint Summary
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|--------|------|------|-------------|
|
||||
| POST | `/api/pick` | No | Pick a random game with filters and repeat avoidance |
|
||||
|
||||
---
|
||||
|
||||
## POST /api/pick
|
||||
|
||||
Select a game using weighted random selection. Filters to only enabled games, applies favor/disfavor bias to influence probability, and optionally excludes recently played games when a session is provided.
|
||||
|
||||
### Authentication
|
||||
|
||||
None.
|
||||
|
||||
### Request Body
|
||||
|
||||
All fields optional. Provide only the filters you want to apply.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| playerCount | integer | No | Filter games where `min_players ≤ count ≤ max_players` |
|
||||
| drawing | string | No | `"only"` = Drawing type only, `"exclude"` = exclude Drawing type |
|
||||
| length | string | No | `"short"` (≤15 min or NULL), `"medium"` (16–25 min), `"long"` (>25 min) |
|
||||
| familyFriendly | boolean | No | Filter by family-friendly rating |
|
||||
| sessionId | integer | No | Session ID for repeat avoidance |
|
||||
| excludePlayed | boolean | No | When `true`, exclude ALL games played in session. Default: exclude last 2 only |
|
||||
|
||||
```json
|
||||
{
|
||||
"playerCount": 6,
|
||||
"drawing": "exclude",
|
||||
"length": "short",
|
||||
"familyFriendly": true,
|
||||
"sessionId": 3,
|
||||
"excludePlayed": false
|
||||
}
|
||||
```
|
||||
|
||||
### Filters
|
||||
|
||||
- **Enabled games only:** Only games with `enabled = 1` are considered.
|
||||
- **playerCount:** Filters games where `min_players ≤ playerCount ≤ max_players`.
|
||||
- **drawing:** `"only"` = games with `game_type = 'Drawing'`; `"exclude"` = games that are not Drawing type.
|
||||
- **length:** `"short"` = ≤15 min (includes NULL); `"medium"` = 16–25 min; `"long"` = >25 min.
|
||||
- **familyFriendly:** `true` or `false` filters by `family_friendly`.
|
||||
|
||||
### Weighted Selection
|
||||
|
||||
- **Game favor_bias:** `1` = 3× weight, `0` = 1× weight, `-1` = 0.2× weight.
|
||||
- **Pack favor_bias:** `1` = 2× weight, `0` = 1× weight, `-1` = 0.3× weight.
|
||||
- Game and pack biases multiply together.
|
||||
|
||||
### Repeat Avoidance (with sessionId)
|
||||
|
||||
- **Default (`excludePlayed: false`):** Excludes the last 2 played games in the session.
|
||||
- **With `excludePlayed: true`:** Excludes ALL games played in the session.
|
||||
|
||||
### Response
|
||||
|
||||
**200 OK**
|
||||
|
||||
```json
|
||||
{
|
||||
"game": {
|
||||
"id": 42,
|
||||
"pack_name": "Jackbox Party Pack 7",
|
||||
"title": "Quiplash 3",
|
||||
"min_players": 3,
|
||||
"max_players": 8,
|
||||
"length_minutes": 15,
|
||||
"has_audience": 1,
|
||||
"family_friendly": 0,
|
||||
"game_type": "Writing",
|
||||
"secondary_type": null,
|
||||
"play_count": 0,
|
||||
"popularity_score": 0,
|
||||
"enabled": 1,
|
||||
"favor_bias": 0,
|
||||
"created_at": "2024-01-15T12:00:00.000Z"
|
||||
},
|
||||
"poolSize": 15,
|
||||
"totalEnabled": 17
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| game | Full game object for the selected game |
|
||||
| poolSize | Number of games in the eligible pool after filters |
|
||||
| totalEnabled | Approximate total enabled games (includes excluded when sessionId provided) |
|
||||
|
||||
### Error Responses
|
||||
|
||||
| Status | Body | When |
|
||||
|--------|------|------|
|
||||
| 404 | `{ "error": "No games match the current filters", "suggestion": "Try adjusting your filters or enabling more games" }` | No games match the filters |
|
||||
| 404 | `{ "error": "All eligible games have been played in this session", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5, 12] }` | All eligible games already played in session (when `excludePlayed: true`) |
|
||||
| 404 | `{ "error": "All eligible games have been played recently", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5] }` | Last 2 games are the only matches (when `excludePlayed: false`) |
|
||||
| 500 | `{ "error": "..." }` | Server error |
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:5000/api/pick" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"playerCount": 6,
|
||||
"drawing": "exclude",
|
||||
"length": "short",
|
||||
"familyFriendly": true,
|
||||
"sessionId": 3,
|
||||
"excludePlayed": false
|
||||
}'
|
||||
```
|
||||
Reference in New Issue
Block a user