john-okeefe
c2f72ca785
The Bruno collection docs mislabeled the rating system and referenced endpoints that do not exist. - Update Media Rating.yml: the rating value is a 1-10 integer scale (displayed as 1-5 stars with half-star precision), not "typically 1-5". - opencollection.yml: the rating routes live under /api/media-items/:id/rating (not /api/ratings/:media_id), GET returns null (not 0) when unrated, and document the PUT upsert route. Correct the scale to 1-10 here as well.
205 lines
12 KiB
YAML
205 lines
12 KiB
YAML
opencollection: 1.0.0
|
|
|
|
info:
|
|
name: Bookhoard
|
|
config:
|
|
proxy:
|
|
inherit: true
|
|
config:
|
|
protocol: http
|
|
hostname: ""
|
|
port: ""
|
|
auth:
|
|
username: ""
|
|
password: ""
|
|
bypassProxy: ""
|
|
|
|
request:
|
|
auth:
|
|
type: bearer
|
|
token: "{{token}}"
|
|
|
|
docs:
|
|
content: |-
|
|
# Bruno OpenCollection YAML API Tests for Bookhoard
|
|
This directory contains Bruno OpenCollection YAML format tests for testing the Bookhoard API with comprehensive REST documentation.
|
|
Setup
|
|
1. Install Bruno: https://www.usebruno.com/
|
|
2. Open Bruno and import this collection folder
|
|
3. Select the "localhost" environment
|
|
4. Start the application with `podman-compose up --build` or `docker-compose up --build`
|
|
5. Register/Login first, then use Bearer token for protected endpoints
|
|
Available Tests
|
|
Authentication (Public & Private)
|
|
- **Register User**: POST /api/auth/register - Create new account with role-based restrictions
|
|
- **Login User**: POST /api/auth/login - Authenticate (email or username)
|
|
- **Refresh Token**: POST /api/auth/refresh - Get new access token
|
|
- **Logout**: POST /api/auth/logout - Invalidate refresh token
|
|
User Profile Management
|
|
- **Get Profile**: GET /api/auth/profile - Get current user info
|
|
- **Update Profile**: PUT /api/auth/profile - Update first_name, last_name
|
|
- **Update Email**: PUT /api/auth/email - Update email address
|
|
- **Update Username**: PUT /api/auth/username - Update username
|
|
- **Update Password**: PUT /api/auth/password - Update password
|
|
- **Update Theme**: PUT /api/auth/theme - Update theme preference
|
|
Admin User Management
|
|
- **List Users**: GET /api/auth/users - Get all users with complete info (admin only)
|
|
- **Delete Account**: DELETE /api/auth/account - Delete own account or admin deletes other accounts
|
|
Libraries (Admin Only)
|
|
- **Create Library**: POST /api/libraries - Create new library (Ebooks, Comics, Manga)
|
|
- **Get Libraries**: GET /api/libraries - List all libraries (admin)
|
|
- **Get Library**: GET /api/libraries/:id - Get library details
|
|
- **Update Library**: PUT /api/libraries/:id - Update library settings
|
|
- **Delete Library**: DELETE /api/libraries/:id - Remove library
|
|
- **Add Library Folder**: POST /api/libraries/:id/folders - Add scanning folder
|
|
- **Get Library Folders**: GET /api/libraries/:id/folders - List folders
|
|
- **Delete Library Folder**: DELETE /api/libraries/:id/folders/:folder_id - Remove folder
|
|
- **Get Library Stats**: GET /api/libraries/:id/stats - Library statistics
|
|
- **Get Library Types**: GET /api/libraries/types - Available library types
|
|
Media Items (Mixed Access)
|
|
- **List Media Items**: GET /api/media-items - Paginated list (filter/sort by library, author, series, etc.)
|
|
- **Get Media Item**: GET /api/media-items/:id - Single item details (all users)
|
|
- **Create Media Item**: POST /api/media-items - Add new item (admin only)
|
|
- **Update Media Item**: PUT /api/media-items/:id - Modify metadata (admin only)
|
|
- **Delete Media Item**: DELETE /api/media-items/:id - Remove item (admin only)
|
|
- **Filter Media Items**: POST /api/media-items/filter - Advanced filtering
|
|
- **EPUB Download**: GET /api/media-items/:id/download - Download EPUB file
|
|
- **Cover Image**: GET /api/media-items/:id/cover - Get cover image
|
|
Reading Progress (All Users)
|
|
- **Get Progress**: GET /api/progress/:media_id - User's reading progress for media item
|
|
- **Update Progress**: PUT /api/progress/:media_id - Update reading progress
|
|
- **Get Device Progress**: GET /api/progress/device/:device_id - Progress by device
|
|
Universal Progress (All Users)
|
|
- **Get Universal Progress**: GET /api/universal-progress/:sha256 - Get progress by book hash
|
|
- **Update Universal Progress**: PUT /api/universal-progress - Update universal progress
|
|
Notes (All Users)
|
|
- **Get Notes**: GET /api/notes/:media_id - Get notes for media item
|
|
- **Create Note**: POST /api/notes - Add new note
|
|
- **Update Note**: PUT /api/notes/:id - Update note content
|
|
- **Delete Note**: DELETE /api/notes/:id - Remove note
|
|
Highlights (All Users)
|
|
- **Get Highlights**: GET /api/highlights/:media_id - Get highlights for media item
|
|
- **Create Highlight**: POST /api/highlights - Add new highlight
|
|
- **Update Highlight**: PUT /api/highlights/:id - Update highlight
|
|
- **Delete Highlight**: DELETE /api/highlights/:id - Remove highlight
|
|
Ratings (All Users)
|
|
- **Get Rating**: GET /api/media-items/:id/rating - User's rating (returns null if unrated)
|
|
- **Create/Update Rating**: POST /api/media-items/:id/rating - Rate media item (1-10 scale, displayed as 1-5 stars with half-star precision). POST upserts; PUT also available.
|
|
- **Update Rating**: PUT /api/media-items/:id/rating - Update rating (upsert)
|
|
- **Delete Rating**: DELETE /api/media-items/:id/rating - Remove rating
|
|
Collections (All Users)
|
|
- **List Collections**: GET /api/collections - Get user's collections
|
|
- **Get Collection**: GET /api/collections/:id - Collection details with media items
|
|
- **Create Collection**: POST /api/collections - Create new collection
|
|
- **Update Collection**: PUT /api/collections/:id - Update collection
|
|
- **Delete Collection**: DELETE /api/collections/:id - Remove collection
|
|
- **Add Auto-Assign Rule**: POST /api/collections/:id/rules - Add automatic rule
|
|
- **Remove Auto-Assign Rule**: DELETE /api/collections/:id/rules/:rule_id - Remove rule
|
|
- **Test Rule**: POST /api/collections/:id/rules/test - Preview rule matches
|
|
- **Bulk Assign**: POST /api/collections/:id/assign - Manually add media items
|
|
Device Management (All Users)
|
|
- **Register Device**: POST /api/devices/register - Register new device
|
|
- **List Devices**: GET /api/devices - Get user's devices
|
|
- **Get Device**: GET /api/devices/:id - Device details
|
|
- **Delete Device**: DELETE /api/devices/:id - Unregister device
|
|
- **Sync Device**: POST /api/devices/:id/sync - Trigger device sync
|
|
Sync Protocols (Device Integration)
|
|
- **KOReader Sync**: POST /api/sync/koreader - KOReader progress/notes/highlights sync
|
|
- **Kobo Sync**: POST /api/sync/kobo - Kobo progress/notes/highlights sync
|
|
Scanner (Admin Only)
|
|
- **Scan Libraries**: POST /api/scanner/scan - Scan library folders
|
|
- **Start Scanner**: POST /api/scanner/start - Start real-time monitoring
|
|
- **Stop Scanner**: POST /api/scanner/stop - Stop monitoring
|
|
- **Get Scan Settings**: GET /api/scanner/settings - Scan configuration
|
|
Analytics (Admin Only)
|
|
- **Get Analytics**: GET /api/analytics - Usage statistics and metrics
|
|
Book Matching (All Users)
|
|
- **Search Books**: GET /api/book-matching/search - Search by ISBN, title, author
|
|
- **Link Book**: POST /api/book-matching/link - Link media item to external database
|
|
OPDS (All Users)
|
|
- **OPDS Feeds**: GET /opds/* - OPDS catalog for e-reader integration
|
|
- **OPDS Acquisition**: GET /opds/acquisition/* - Download media items
|
|
WebSocket (Real-time)
|
|
- **WebSocket**: WS /ws/sync - Real-time sync events (progress, notes, highlights)
|
|
Collection Organization
|
|
bruno/
|
|
├── user/ # User authentication and profile
|
|
│ ├── auth/ # Login, register, refresh
|
|
│ ├── profile/ # Profile management
|
|
│ └── admin/ # User administration (admin only)
|
|
├── library/ # Library management
|
|
│ ├── Create/Update/Delete Libraries
|
|
│ ├── Library Folders
|
|
│ ├── Library Stats
|
|
│ └── Scan Settings
|
|
├── media-items/ # Media item operations
|
|
│ ├── List/Get/Create/Update/Delete
|
|
│ ├── Filter and Sort
|
|
│ ├── Download EPUB
|
|
│ ├── Cover Images
|
|
│ └── Ratings
|
|
├── progress/ # Reading progress tracking
|
|
├── universal-progress/ # Cross-device universal progress
|
|
├── notes/ # User notes
|
|
├── highlights/ # Book highlights
|
|
├── collections/ # Smart collections
|
|
├── devices/ # Device registration
|
|
├── sync-koreader/ # KOReader sync protocol
|
|
├── sync-kobo/ # Kobo sync protocol
|
|
├── scanner/ # Library scanning
|
|
├── analytics/ # Usage statistics
|
|
├── books/ # Book matching/linking
|
|
├── kobo/ # Kobo-specific operations
|
|
├── koreader/ # KOReader-specific operations
|
|
├── opds/ # OPDS catalog feeds
|
|
└── admin/ # Admin operations
|
|
## Security Features
|
|
### Registration Restrictions
|
|
- **First User**: Automatically gets admin role regardless of request
|
|
- **Existing Admins**: Only authenticated admins can create new admin accounts
|
|
- **Regular Users**: Anyone can create regular user accounts
|
|
- **Unauthenticated**: Can only create first admin, not subsequent admins
|
|
### User Management
|
|
- **Self-Deletion**: Users can delete their own accounts
|
|
- **Admin Override**: Admins can delete any user account
|
|
- **Last Admin Protection**: Cannot delete the last admin account in the system
|
|
### Role System
|
|
- **Admin**: Full access - manage libraries, media items, users, scanner
|
|
- **User**: Read access - view media items, create collections, track progress, rate, annotate
|
|
### Device Authentication
|
|
- **No Passwords**: Devices use QR code registration and access tokens
|
|
- **User Approval**: Device registration requires user approval via web interface
|
|
### JWT Tokens
|
|
- **Access Token**: Valid for 1 hour, sent via Bearer header
|
|
- **Refresh Token**: Valid for 7 days, used to get new access tokens
|
|
### Rate Limiting
|
|
- **Auth Endpoints**: 10 requests/minute per IP
|
|
### Data Isolation
|
|
- **Progress, Notes, Highlights, Ratings**: User-specific
|
|
- **Collections**: User-specific (admins see all users' collections)
|
|
- **Devices**: User-specific
|
|
## Documentation Features
|
|
Each request includes:
|
|
- **Detailed descriptions** of functionality
|
|
- **Parameter specifications** (required/optional, types)
|
|
- **Request/Response examples**
|
|
- **Error response codes** and meanings
|
|
- **Authentication requirements**
|
|
## Notes
|
|
- **Authentication Flow**: Register → Login → Use Bearer token for all other requests
|
|
- **Media Items vs Books**: The API uses "media items" (supports ebooks, comics, manga)
|
|
- **Library System**: Organized by libraries (Ebooks, Comics, Manga) with scanning folders
|
|
- **Universal Progress**: Cross-device sync using SHA-256 book hashes
|
|
- **Smart Collections**: Auto-assign rules based on genre, author, series, tags, etc.
|
|
- **OPDS Support**: Wireless book delivery to e-readers (Kobo, KOReader)
|
|
- **Device Protocols**: Native sync for KOReader and Kobo devices
|
|
- **Rating System**: Half-star precision (1-10 scale internally, displayed as 1-5 stars)
|
|
- **Admin Setup**: First admin must be created by updating user role in database
|
|
- **Variables**: Update collection variables for testing (media_id, library_id, device_id, etc.)
|
|
- **Security**: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
|
|
- **JSON**: All requests/responses use JSON format
|
|
- **WebSocket**: Real-time events for sync updates across devices
|
|
type: text/markdown
|
|
bundled: false
|
|
extensions: {}
|