john-okeefe
48b6796bcd
- Update README.md with admin system documentation - Add admin setup instructions and role permissions - Update API endpoint documentation with access requirements - Update Bruno collection to reflect admin-only operations - Document shared library concept and security model - Add comprehensive admin setup guide
3.3 KiB
3.3 KiB
Bruno API Tests for Bookmann
This directory contains Bruno collection for testing the Bookmann API with comprehensive REST documentation.
Setup
- Install Bruno: https://www.usebruno.com/
- Open Bruno and import this collection folder
- Select the "localhost" environment
- Start the application with
docker-compose up --build - Register/Login first, then use Bearer token for protected endpoints
Available Tests
Auth (Public Endpoints)
- Register User: POST /api/auth/register - Create new account
- Login User: POST /api/auth/login - Authenticate (email or username)
- Get Profile: GET /api/auth/profile - Get user info (requires token)
Folders (Admin Only)
- Add Ebook Folder: POST /api/auth/ebook-folders - Add folder for scanning (admin only)
- Get Ebook Folders: GET /api/auth/ebook-folders - List configured folders (admin only)
- Delete Ebook Folder: DELETE /api/auth/ebook-folders - Remove folder (admin only)
Ebooks (Mixed Access)
- List Ebooks: GET /api/ebooks - Paginated ebook list (all authenticated users)
- Get Ebook: GET /api/ebooks/:id - Single ebook details (all authenticated users)
- Create Ebook: POST /api/ebooks - Add new ebook (admin only)
- Update Ebook: PUT /api/ebooks/:id - Modify ebook metadata (admin only)
- Delete Ebook: DELETE /api/ebooks/:id - Remove ebook (admin only)
Scanner (Admin Only)
- Scan Ebooks: POST /api/scanner/scan - Scan configured folders (admin only)
- Start Scanner: POST /api/scanner/start - Start real-time monitoring (admin only)
- Stop Scanner: POST /api/scanner/stop - Stop monitoring (admin only)
Reading Progress (All Users)
- Get Reading Progress: GET /api/ebooks/:id/progress - User's progress
- Update Reading Progress: PUT /api/ebooks/:id/progress - Update progress
Ratings (All Users)
- Get Ebook Rating: GET /api/ebooks/:id/rating - User's rating for ebook (returns 0 if unrated)
- Create/Update Rating: POST /api/ebooks/:id/rating - Rate ebook (1-5 stars)
- Delete Rating: DELETE /api/ebooks/:id/rating - Remove user's rating
- Get All Ratings: GET /api/ebooks/:id/ratings - All ratings for ebook
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
- JWT Tokens: Valid for 24 hours, include in
Authorization: Bearer <token>header - Role System: Two roles - 'admin' and 'user'. Admins can manage folders and ebooks, users can view/rate/track progress
- Shared Library: All users can view the complete ebook collection, but only admins can modify it
- User Isolation: Progress, ratings, and profile data are user-specific
- Rating Behavior: Get rating returns 0 when no rating exists (instead of 404)
- Admin Setup: First admin must be created by updating user role in database:
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com'; - Variables: Update
ebook_idfor testing specific ebooks - Security: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
- JSON: All requests/responses use JSON format