john-okeefe
481adaa71e
- Add role-based restrictions to POST /api/auth/register endpoint - Only admins can create admin accounts if any admin already exists - First user automatically gets admin role regardless of request - Regular users can only create user accounts, not admin accounts - Unauthenticated users can only create first admin, not subsequent admins - Reorganize Bruno collection into logical subfolders (auth/, admin/, profile/) - Update documentation to reflect new registration restrictions and security rules BREAKING CHANGES: - /api/auth/register now enforces role-based creation restrictions - Bruno collection reorganized with subfolder structure
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)
User Management (Admin Only)
- List Users: GET /api/auth/users - Get all users with complete profile info (admin only)
- Delete Account: DELETE /api/auth/account - Delete own account or admin deletes other accounts with
user_idparameter (admin only)
User Management (Protected)
- Delete Account: DELETE /api/auth/account - Delete own account (self) or admin deletes other accounts with
user_idparameter (admin only)
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