john-okeefe
71584c1b55
- Add admin override capability to DELETE /api/auth/account endpoint - Move /api/auth/users to admin-only with complete user fields (first_name, last_name, role, theme) - Consolidate Bruno requests: remove duplicate List Users (Admin), merge Delete Account functionality - Update all documentation to reflect enhanced capabilities - Implement pgx 5 standards compliance with proper error handling BREAKING CHANGES: - /api/auth/users endpoint now requires admin role (was previously accessible) - DELETE /api/auth/account accepts optional user_id parameter for admin deletion
74 lines
3.8 KiB
Markdown
74 lines
3.8 KiB
Markdown
# Bruno API Tests for Bookmann
|
|
|
|
This directory contains Bruno collection for testing the Bookmann 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 `docker-compose up --build`
|
|
5. 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_id` parameter (admin only)
|
|
|
|
### User Management (Protected)
|
|
- **Delete Account**: DELETE /api/auth/account - Delete own account (self) or admin deletes other accounts with `user_id` parameter (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_id` for testing specific ebooks
|
|
- **Security**: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
|
|
- **JSON**: All requests/responses use JSON format |