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.
This commit is contained in:
@@ -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 <admin_token>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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 <admin_token>" \
|
||||
-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
|
||||
Reference in New Issue
Block a user