From efa046d030cb279a0ad4b8f8af2ef86ce41fc1fb Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 08:51:53 -0500 Subject: [PATCH] docs: add ratings, devices, and analytics API endpoints Phase 2 part 5: Split device management and analytics endpoints - Ratings: get_ratings, create_rating (1-10 scale with half-stars) - Devices: register_device, list_devices, get_devices, revoke_device - Analytics: get_analytics (reading statistics) - Include device registration flow details --- docs/api/analytics/get_analytics.md | 49 +++++++++++++++++++++++ docs/api/devices/get_devices.md | 62 +++++++++++++++++++++++++++++ docs/api/devices/list_devices.md | 48 ++++++++++++++++++++++ docs/api/devices/register_device.md | 48 ++++++++++++++++++++++ docs/api/devices/revoke_device.md | 41 +++++++++++++++++++ docs/api/ratings/create_rating.md | 52 ++++++++++++++++++++++++ docs/api/ratings/get_ratings.md | 48 ++++++++++++++++++++++ 7 files changed, 348 insertions(+) create mode 100644 docs/api/analytics/get_analytics.md create mode 100644 docs/api/devices/get_devices.md create mode 100644 docs/api/devices/list_devices.md create mode 100644 docs/api/devices/register_device.md create mode 100644 docs/api/devices/revoke_device.md create mode 100644 docs/api/ratings/create_rating.md create mode 100644 docs/api/ratings/get_ratings.md diff --git a/docs/api/analytics/get_analytics.md b/docs/api/analytics/get_analytics.md new file mode 100644 index 0000000..8b202b7 --- /dev/null +++ b/docs/api/analytics/get_analytics.md @@ -0,0 +1,49 @@ +# Get Reading Statistics + +Retrieve reading statistics for a date range. + +**Endpoint**: `GET /api/analytics/reading-stats` +**Auth**: Required + +## Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| start_date | string | No | Start date (ISO 8601 format) | +| end_date | string | No | End date (ISO 8601 format) | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/analytics/reading-stats?start_date=2026-01-01&end_date=2026-01-31 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "pages_read": 1250, + "books_completed": 5, + "reading_time_hours": 42.5, + "sessions_count": 28, + "average_session_minutes": 91 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid date format | +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/devices/get_devices.md b/docs/api/devices/get_devices.md new file mode 100644 index 0000000..f49a67b --- /dev/null +++ b/docs/api/devices/get_devices.md @@ -0,0 +1,62 @@ +# Get Device / Check Registration Status + +Check device registration status or get device details. + +**Endpoint**: `POST /api/devices/auth/status` or `GET /api/devices/{device_id}` +**Auth**: Not required for status check, Required for device details +**Content-Type**: `application/json` (for status check) + +## Request Body (Status Check) + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| registration_id | string | Yes | Registration UUID | + +### Example Request (Status Check) + +```json +{ + "registration_id": "registration-uuid" +} +``` + +## Response (200 OK) + +```json +{ + "status": "pending|approved|expired", + "auth_token": "device-bearer-token...", + "device_id": "uuid", + "sync_endpoints": { + "progress": "https://bookhoard.com/api/sync/progress", + "metadata": "https://bookhoard.com/api/sync/metadata", + "annotations": "https://bookhoard.com/api/sync/annotations" + } +} +``` + +## Response (200 OK) - Device Details + +```json +{ + "id": "uuid", + "device_name": "My Kobo Clara", + "device_type": "kobo", + "last_sync": "2026-01-31T10:00:00Z", + "last_seen": "2026-01-31T10:05:00Z", + "sync_enabled": true, + "auto_sync": true, + "sync_frequency_minutes": 5 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token (for device details) | +| 404 | Device or registration not found | + +## Try It Out + + diff --git a/docs/api/devices/list_devices.md b/docs/api/devices/list_devices.md new file mode 100644 index 0000000..2dde0b4 --- /dev/null +++ b/docs/api/devices/list_devices.md @@ -0,0 +1,48 @@ +# List User Devices + +Retrieve all devices registered to the current user. + +**Endpoint**: `GET /api/devices` +**Auth**: Required + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/devices +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "devices": [ + { + "id": "uuid", + "device_name": "My Kobo Clara", + "device_type": "kobo", + "last_sync": "2026-01-31T10:00:00Z", + "last_seen": "2026-01-31T10:05:00Z", + "sync_enabled": true, + "auto_sync": true, + "sync_frequency_minutes": 5 + } + ] +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/devices/register_device.md b/docs/api/devices/register_device.md new file mode 100644 index 0000000..6cc1b5d --- /dev/null +++ b/docs/api/devices/register_device.md @@ -0,0 +1,48 @@ +# Register Device + +Register a new device for sync. + +**Endpoint**: `POST /api/devices/register` +**Auth**: Not required (device registration flow) +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| device_name | string | Yes | Device name | +| device_type | string | Yes | Device type: kobo, koreader, web, mobile | +| device_identifier | string | Yes | Hardware-specific ID | + +### Example Request + +```json +{ + "device_name": "My Kobo Clara", + "device_type": "kobo", + "device_identifier": "hardware-specific-id" +} +``` + +## Response (201 Created) + +```json +{ + "device_id": "uuid", + "registration_id": "registration-uuid", + "auth_url": "https://bookhoard.com/devices/auth/confirm/abc123", + "qr_code": "data:image/png;base64,iVBORw0KG...", + "expires_in": 300 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid device data | +| 409 | Device already registered | + +## Try It Out + + diff --git a/docs/api/devices/revoke_device.md b/docs/api/devices/revoke_device.md new file mode 100644 index 0000000..91b6145 --- /dev/null +++ b/docs/api/devices/revoke_device.md @@ -0,0 +1,41 @@ +# Revoke Device + +Revoke access to a device. + +**Endpoint**: `DELETE /api/devices/{device_id}` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| device_id | string | Yes | Device UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/devices/uuid +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Device revoked successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not own this device | +| 404 | Device not found | + +## Try It Out + + diff --git a/docs/api/ratings/create_rating.md b/docs/api/ratings/create_rating.md new file mode 100644 index 0000000..b150034 --- /dev/null +++ b/docs/api/ratings/create_rating.md @@ -0,0 +1,52 @@ +# Create Rating + +Set a rating for a media item. Creates a new rating or updates an existing one. + +**Endpoint**: `POST /api/media-items/{media_id}/rating` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| rating | integer | Yes | Rating from 1-10 | + +### Example Request + +```json +{ + "rating": 8 +} +``` + +## Response (201 Created) + +```json +{ + "rating": 8, + "user_id": "uuid", + "media_item_id": "uuid", + "created_at": "2026-01-31T10:00:00Z" +} +``` + +**Rating Scale**: 1-10 (odd numbers = half-stars: 1=0.5★, 2=1★, 3=1.5★, ..., 9=4.5★, 10=5★) + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid rating (must be 1-10) | +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/ratings/get_ratings.md b/docs/api/ratings/get_ratings.md new file mode 100644 index 0000000..6ccca4a --- /dev/null +++ b/docs/api/ratings/get_ratings.md @@ -0,0 +1,48 @@ +# Get Rating + +Retrieve the current user's rating for a media item. + +**Endpoint**: `GET /api/media-items/{media_id}/rating` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/media-items/uuid/rating +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "rating": 8, + "user_id": "uuid", + "media_item_id": "uuid" +} +``` + +**Rating Scale**: 1-10 (odd numbers = half-stars: 1=0.5★, 2=1★, 3=1.5★, ..., 9=4.5★, 10=5★) + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Media item not found or no rating set | + +## Try It Out + +