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
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/logout - User logout
- GET /api/auth/profile - Get user profile
- PUT /api/auth/profile - Update user profile
- PUT /api/auth/email - Update user email
- PUT /api/auth/username - Update username
- PUT /api/auth/password - Change password
- PUT /api/auth/profile - Update user profile (self-edit)
- PUT /api/auth/profile/:id - Update user profile (admin)
- DELETE /api/auth/profile - Delete account (self)
- 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
## Admin
docs/developer/api/users/change_password.md
+48 -12
View File
@@ -1,35 +1,71 @@
# 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
**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 |
|--------|------|-----------|-------------|
| current_password | string | Yes | Current password |
| new_password | string | Yes | New password (min 8 chars) |
| current_password | string | Yes | Current password for verification |
| new_password | string | Yes | New password (min 8 chars, complexity required) |
| confirm_password | string | Yes | Must match new_password |
### Example Request
```json
{
"current_password": "oldPassword",
"new_password": "NewSecureP@ss123!"
"current_password": "OldPassword123!",
"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
| Code | Description |
|------|-------------|
| 400 | Invalid input or weak password |
| 401 | Current password is incorrect |
| 401 | Invalid or expired token |
| 400 | Invalid input, weak password, or passwords don't match |
| 401 | Current password is incorrect (self-service mode) |
| 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 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
**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 |
|--------|------|-----------|-------------|
| 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 |
| last_name | string | No | User's last name |
| theme | string | No | Theme preference |
### Example Request
```json
{
"username": "newusername",
"email": "newemail@example.com",
"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",
"first_name": "John",
"last_name": "Smith",
"theme": "tokyo-night",
"theme": "dracula",
"role": "user",
"max_devices": 10,
"created_at": "2026-01-31T10:00:00Z"
@@ -42,5 +77,8 @@ Update the current user's profile information.
| Code | Description |
|------|-------------|
| 400 | Invalid input data |
| 400 | Invalid input data or invalid role |
| 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 |