From 90603b7a48cf5aea84375d558fa61cdb26319269 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 9 Feb 2026 20:11:56 -0500 Subject: [PATCH] docs: add system settings API documentation and update user list docs System Settings API Documentation (new): - docs/developer/api/system/settings.md - Document GET /api/libraries/scan-settings endpoint - Document PUT /api/libraries/scan-settings endpoint - Include request/response examples - Document validation rules and error codes - Include migration notes from per-user to system-wide User List API Documentation (update): - docs/developer/api/admin/list_users.md - Add max_devices field to response - Add device_count field to response - Include complete response field descriptions table - Update example to show new fields Documentation covers both the new system-wide scan settings feature and the enhanced user list with device monitoring capabilities. --- docs/developer/api/admin/list_users.md | 27 +++- docs/developer/api/system/settings.md | 168 +++++++++++++++++++++++++ 2 files changed, 193 insertions(+), 2 deletions(-) create mode 100644 docs/developer/api/system/settings.md diff --git a/docs/developer/api/admin/list_users.md b/docs/developer/api/admin/list_users.md index 845e75b..e1c0f2b 100644 --- a/docs/developer/api/admin/list_users.md +++ b/docs/developer/api/admin/list_users.md @@ -35,10 +35,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... "id": "uuid", "email": "user@example.com", "username": "johndoe", + "first_name": "John", + "last_name": "Doe", "role": "user", + "theme": "tokyo-night", "max_devices": 10, - "active_devices": 3, - "created_at": "2026-02-08T10:00:00Z" + "device_count": 3, + "created_at": "2026-02-08T10:00:00Z", + "updated_at": "2026-02-08T10:00:00Z" } ], "total": 25, @@ -47,6 +51,25 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... } ``` +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | User ID (UUID) | +| `email` | string | Email address | +| `username` | string | Username | +| `first_name` | string | First name (optional) | +| `last_name` | string | Last name (optional) | +| `role` | string | User role (`"user"` or `"admin"`) | +| `theme` | string | Theme preference (optional) | +| `max_devices` | integer | Maximum number of devices allowed | +| `device_count` | integer | Current number of registered devices | +| `created_at` | string | Account creation timestamp (ISO 8601) | +| `updated_at` | string | Last update timestamp (ISO 8601) | +| `total` | integer | Total number of users matching query | +| `limit` | integer | Limit applied to this request | +| `offset` | integer | Offset applied to this request | + ## Error Responses | Code | Description | diff --git a/docs/developer/api/system/settings.md b/docs/developer/api/system/settings.md new file mode 100644 index 0000000..254eb9b --- /dev/null +++ b/docs/developer/api/system/settings.md @@ -0,0 +1,168 @@ +# System Scan Settings API + +## Overview + +The System Scan Settings API allows administrators to configure system-wide scan settings that apply to all libraries. These settings control the automatic scanning behavior for the entire Bookhoard system. + +**Base URL**: `/api/libraries` +**Authentication**: Admin JWT token required +**Content-Type**: `application/json` + +--- + +## Endpoints + +### Get System Scan Settings + +Retrieve the current system-wide scan settings. + +**Endpoint**: `GET /api/libraries/scan-settings` + +**Authentication**: Admin role required + +**Response**: +- **200 OK**: Returns current scan settings +- **401 Unauthorized**: Invalid or missing authentication +- **403 Forbidden**: User does not have admin role +- **500 Internal Server Error**: Server error + +**Response Body**: +```json +{ + "scan_frequency_minutes": 60, + "auto_scan_enabled": true +} +``` + +**Fields**: +- `scan_frequency_minutes` (integer): How often to scan all libraries in minutes (15-1440) +- `auto_scan_enabled` (boolean): Whether auto-scanning is enabled system-wide + +**Example**: +```bash +curl -X GET https://bookhoard.example.com/api/libraries/scan-settings \ + -H "Authorization: Bearer " +``` + +--- + +### Update System Scan Settings + +Update the system-wide scan settings. + +**Endpoint**: `PUT /api/libraries/scan-settings` + +**Authentication**: Admin role required + +**Request Body**: +```json +{ + "scan_frequency_minutes": 30, + "auto_scan_enabled": true +} +``` + +**Fields**: +- `scan_frequency_minutes` (integer, required): How often to scan all libraries in minutes + - Minimum: 15 (15 minutes) + - Maximum: 1440 (24 hours) + - Default: 60 +- `auto_scan_enabled` (boolean, required): Whether auto-scanning is enabled system-wide + - Default: true + +**Response**: +- **200 OK**: Settings updated successfully +- **400 Bad Request**: Invalid request parameters +- **401 Unauthorized**: Invalid or missing authentication +- **403 Forbidden**: User does not have admin role +- **500 Internal Server Error**: Server error + +**Success Response Body**: +```json +{ + "scan_frequency_minutes": 30, + "auto_scan_enabled": true, + "message": "scan settings updated successfully" +} +``` + +**Error Response Body**: +```json +{ + "error": "error message" +} +``` + +**Validation Rules**: +- `scan_frequency_minutes` must be between 15 and 1440 minutes +- Both fields are required + +**Example**: +```bash +curl -X PUT https://bookhoard.example.com/api/libraries/scan-settings \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "scan_frequency_minutes": 30, + "auto_scan_enabled": true + }' +``` + +--- + +## Behavior + +### Scan Frequency + +The `scan_frequency_minutes` setting determines how often the system will automatically scan all libraries for new media files. The scheduler will trigger scans for all libraries at the configured interval. + +**Constraints**: +- Minimum: 15 minutes (to prevent excessive scanning) +- Maximum: 1440 minutes (24 hours) +- Default: 60 minutes (1 hour) + +### Auto-Scan Toggle + +The `auto_scan_enabled` setting acts as a master switch for automatic scanning: +- When `true`: All libraries will be scanned automatically at the configured interval +- When `false`: No automatic scans will occur (manual scans still available) + +### System-Wide Scope + +These settings apply to **all libraries** in the system. Individual users can no longer configure per-user scan settings. This ensures consistent scanning behavior across the entire Bookhoard instance. + +--- + +## Error Codes + +| Status Code | Error Description | +|-------------|-------------------| +| 400 | Invalid request parameters (e.g., frequency outside range) | +| 401 | Missing or invalid JWT token | +| 403 | User lacks admin role | +| 500 | Internal server error (e.g., database connection issue) | + +--- + +## Related Endpoints + +- `POST /api/libraries/{id}/scan` - Manually trigger a scan for a specific library (admin only) +- `GET /api/libraries` - List all libraries +- `GET /api/libraries/{id}` - Get details for a specific library + +--- + +## Migration Notes + +This API replaces the previous per-user scan settings system. The following changes were made: + +- **Removed**: Per-user scan settings (previously in users table) +- **Added**: System-wide scan settings (now in system_settings table) +- **Changed**: Access control from user-specific to admin-only +- **Preserved**: Endpoint paths remain the same for backward compatibility + +The migration ensures that: +1. All libraries scan at the same frequency +2. Only administrators can modify scan settings +3. The API endpoints remain unchanged for existing clients +4. The scheduler uses system-wide settings instead of user-specific settings