Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: update API documentation for consolidated user management

Browse Source 
Add documentation for delete_user and reset_user_password endpoints.
Update update_profile to reflect consolidated endpoint. Remove obsolete
documentation for individual update operations. Add profile guide for
end-users. Update API_CONSOLIDATION_PLAN.md with implementation status.
This commit is contained in:
john-okeefe
2026-02-22 01:59:52 -05:00
parent 9ea0ec5a3e
commit ff25454901
9 changed files with 1024 additions and 968 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API_CONSOLIDATION_PLAN.md
+782 -832
View File
File diff suppressed because it is too large Load Diff
docs/developer/api/api-reference.md
+6 -4
View File
@@ -37,10 +37,12 @@ See [Authentication Endpoints](authentication/)
- POST /api/auth/refresh - Refresh access token - POST /api/auth/refresh - Refresh access token
- POST /api/auth/logout - User logout - POST /api/auth/logout - User logout
- GET /api/auth/profile - Get user profile - GET /api/auth/profile - Get user profile
- PUT /api/auth/profile - Update user profile - PUT /api/auth/profile - Update user profile (self-edit)
- PUT /api/auth/email - Update user email - PUT /api/auth/profile/:id - Update user profile (admin)
- PUT /api/auth/username - Update username - DELETE /api/auth/profile - Delete account (self)
- PUT /api/auth/password - Change password - DELETE /api/auth/profile/:id - Delete user (admin)
- PUT /api/auth/password - Change password (self)
- PUT /api/auth/password/:id - Reset password (admin)
- PUT /api/auth/theme - Update theme preference - PUT /api/auth/theme - Update theme preference
## Admin ## Admin
docs/developer/api/users/change_password.md
+48 -12
View File
@@ -1,35 +1,71 @@
# Change Password # Change Password
Change the current user's password. Change user password. Supports both self-service and admin modes.
**Endpoints**:
- Self-service: `PUT /api/auth/password`
- Admin reset: `PUT /api/auth/password/:id`
**Endpoint**: `PUT /api/auth/password`
**Auth**: Required **Auth**: Required
**Content-Type**: `application/json` **Content-Type**: `application/json`
## Request Body ## Self-Service Mode
Users can change their own password by providing current password verification.
### Request Body
| Field | Type | Required | Description | | Field | Type | Required | Description |
|--------|------|-----------|-------------| |--------|------|-----------|-------------|
| current_password | string | Yes | Current password | | current_password | string | Yes | Current password for verification |
| new_password | string | Yes | New password (min 8 chars) | | new_password | string | Yes | New password (min 8 chars, complexity required) |
| confirm_password | string | Yes | Must match new_password |
### Example Request ### Example Request
```json ```json
{ {
"current_password": "oldPassword", "current_password": "OldPassword123!",
"new_password": "NewSecureP@ss123!" "new_password": "NewSecureP@ss123!",
"confirm_password": "NewSecureP@ss123!"
} }
``` ```
## Response (204 No Content) ## Admin Mode
Password changed successfully. Admins can reset any user's password without knowing the current password.
**URL Parameter**: `:id` - Target user's UUID
### Request Body (Admin Mode)
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| new_password | string | Yes | New password (min 8 chars, complexity required) |
| confirm_password | string | Yes | Must match new_password |
### Example Admin Request
```json
{
"new_password": "NewSecureP@ss123!",
"confirm_password": "NewSecureP@ss123!"
}
```
## Response (200 OK)
```json
{
"message": "password updated"
}
```
## Error Responses ## Error Responses
| Code | Description | | Code | Description |
|------|-------------| |------|-------------|
| 400 | Invalid input or weak password | | 400 | Invalid input, weak password, or passwords don't match |
| 401 | Current password is incorrect | | 401 | Current password is incorrect (self-service mode) |
| 401 | Invalid or expired token | | 403 | Admin access required (admin mode only) |
| 404 | User not found (admin mode only) |
docs/developer/api/users/delete_user.md
+46
View File
@@ -0,0 +1,46 @@
# Delete User
Delete a user account. Supports both self-deletion and admin deletion.
**Endpoints**:
- Self-deletion: `DELETE /api/auth/profile`
- Admin deletion: `DELETE /api/auth/profile/:id`
**Auth**: Required
## Self-Deletion
Users can delete their own account. This permanently removes the user and all associated data.
**Endpoint**: `DELETE /api/auth/profile`
## Admin Deletion
Admins can delete any user account by providing the user ID in the URL.
**URL Parameter**: `:id` - Target user's UUID
**Endpoint**: `DELETE /api/auth/profile/:id`
## Response (200 OK)
```json
{
"message": "account deleted"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Cannot delete the last admin |
| 401 | Invalid or expired token |
| 403 | Admin access required (trying to delete another user) |
| 404 | User not found (admin mode only) |
## Safety Rules
- The last remaining admin cannot be deleted
- Self-deletion requires the user to not be the last admin
- Admin deletion is restricted to admin role only
docs/developer/api/users/update_email.md
-37
View File
@@ -1,37 +0,0 @@
# Update Email
Update the authenticated user's email address.
**Endpoint**: `PUT /api/auth/email`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| email | string | Yes | New email address (must be valid email format) |
### Example Request
```json
{
"email": "newemail@example.com"
}
```
## Response (200 OK)
```json
{
"message": "Email updated successfully"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid email format |
| 401 | Invalid or expired token |
| 409 | Email already taken by another user |
docs/developer/api/users/update_profile.md
+44 -6
View File
@@ -1,24 +1,59 @@
# Update Profile # Update Profile
Update the current user's profile information. Update user profile information. Supports both self-edit and admin modes.
**Endpoints**:
- Self-edit: `PUT /api/auth/profile`
- Admin edit: `PUT /api/auth/profile/:id`
**Endpoint**: `PUT /api/auth/profile`
**Auth**: Required **Auth**: Required
**Content-Type**: `application/json` **Content-Type**: `application/json`
## Request Body ## Self-Edit Mode
Users can update their own profile. All fields are optional.
### Request Body
| Field | Type | Required | Description | | Field | Type | Required | Description |
|--------|------|-----------|-------------| |--------|------|-----------|-------------|
| username | string | No | New username (must be unique, 3-50 chars) |
| email | string | No | New email (must be unique, valid format) |
| first_name | string | No | User's first name | | first_name | string | No | User's first name |
| last_name | string | No | User's last name | | last_name | string | No | User's last name |
| theme | string | No | Theme preference |
### Example Request ### Example Request
```json ```json
{ {
"username": "newusername",
"email": "newemail@example.com",
"first_name": "John", "first_name": "John",
"last_name": "Smith" "last_name": "Smith",
"theme": "dracula"
}
```
## Admin Mode
Admins can update any user by providing the user ID in the URL. Additionally supports role changes.
**URL Parameter**: `:id` - Target user's UUID
### Additional Request Body Fields (Admin Only)
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| role | string | No | New role: "user" or "admin" |
### Example Admin Request
```json
{
"username": "newusername",
"email": "newemail@example.com",
"role": "admin"
} }
``` ```
@@ -31,7 +66,7 @@ Update the current user's profile information.
"username": "john", "username": "john",
"first_name": "John", "first_name": "John",
"last_name": "Smith", "last_name": "Smith",
"theme": "tokyo-night", "theme": "dracula",
"role": "user", "role": "user",
"max_devices": 10, "max_devices": 10,
"created_at": "2026-01-31T10:00:00Z" "created_at": "2026-01-31T10:00:00Z"
@@ -42,5 +77,8 @@ Update the current user's profile information.
| Code | Description | | Code | Description |
|------|-------------| |------|-------------|
| 400 | Invalid input data | | 400 | Invalid input data or invalid role |
| 401 | Invalid or expired token | | 401 | Invalid or expired token |
| 403 | Admin access required (admin mode only) |
| 404 | User not found (admin mode only) |
| 409 | Username or email already taken |
docs/developer/api/users/update_theme.md
-40
View File
@@ -1,40 +0,0 @@
# Update Theme
Update the current user's theme preference.
**Endpoint**: `PUT /api/auth/theme`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| theme | string | Yes | Theme name (e.g., "tokyo-night", "dracula") |
### Example Request
```json
{
"theme": "dracula"
}
```
## Response (200 OK)
```json
{
"id": "uuid",
"email": "user@example.com",
"username": "john",
"theme": "dracula",
"role": "user"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid theme name |
| 401 | Invalid or expired token |
docs/developer/api/users/update_username.md
-37
View File
@@ -1,37 +0,0 @@
# Update Username
Update the authenticated user's username.
**Endpoint**: `PUT /api/auth/username`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| username | string | Yes | New username (min 3 chars, alphanumeric and underscore only) |
### Example Request
```json
{
"username": "new_username"
}
```
## Response (200 OK)
```json
{
"message": "Username updated successfully"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid username format |
| 401 | Invalid or expired token |
| 409 | Username already taken by another user |
docs/user/profile-guide.md
+98
View File
@@ -0,0 +1,98 @@
# Profile Management Guide
## Updating Your Profile
Your profile contains your account information and preferences.
### How to Update
1. Click on your **username** (top-right)
2. Select **Profile** from the dropdown
3. Edit any fields in the "Account Information" section
4. Click **Update Profile**
5. Changes take effect immediately
### Fields You Can Update
- **Username** - Your login name (must be unique)
- **Email** - Your email address (must be unique)
- **First Name** - Optional display name
- **Last Name** - Optional display name
- **Theme** - Your preferred color scheme
## Changing Your Password
Regular password changes are recommended for account security.
### How to Change
1. Go to **Profile** page
2. Scroll to "Change Password" section
3. Enter your **current password**
4. Enter your **new password**
5. **Confirm** your new password
6. Click **Update Password**
### Password Requirements
- Minimum 8 characters
- Must contain uppercase, lowercase, number, and special character
- Must match confirmation field
- Current password must be correct
## Deleting Your Account
**⚠️ WARNING:** This action cannot be undone.
### What Gets Deleted
When you delete your account:
- Your profile information
- Reading progress and history
- Device connections
- Collection preferences
- All personal data
### What Stays
- Library books (media belongs to the library, not you)
- System settings
- Other users' accounts
### How to Delete
1. Go to **Profile** page
2. Scroll to "Danger Zone" (bottom of page)
3. Click **Remove My Account**
4. Confirm by clicking "OK" in the popup
**Note:** If you're the last admin, you cannot delete your account for security reasons.
## Theme Options
Personalize your reading experience with different color themes.
### Quick Theme Switch
1. Click the **paintbrush icon** (top-right, next to your username)
2. Select a theme from the dropdown
3. Changes apply instantly
### Available Themes
- **Tokyo Night** (default) - Blue/purple accents
- **Dracula** - Purple/pink tones
- **Nord** - Arctic, bluish-gray
- **Solarized Dark** - Warm, precise contrast
- **Monokai** - Classic vibrant colors
- **One Dark Pro** - Atom editor inspired
- **Material Dark** - Google Material Design
- **Wood Light** - Light wood texture
- **Wood Dark** - Dark wood texture
- **Wood Mahogany** - Reddish-brown wood
## For Admin Users
If you're an administrator, you can also manage other users' profiles from the admin panel.
See [Admin User Management](admin-guide.md) for details.