docs(api): complete backend documentation with all missing endpoints

Complete API documentation audit covering all backend endpoints.

Auth Endpoints:
- Fixed endpoint paths from /api/users/me/* to /api/auth/*
- Added update_email.md and update_username.md

Device Management:
- Device shelf operations (add, get, remove, clear)
- Device CRUD operations (update, delete)
- Registration management (pending, approve, reject)

Books Operations:
- Bulk delete and bulk update with normalization
- Download endpoint with format-specific headers

Conflict Resolution:
- Complete conflict management (list, get, resolve, delete)
- Bulk operations (bulk resolve, bulk dismiss, dismiss all)

Sync Protocols:
- KOReader: progress, metadata, library, bookmarks
- Kobo: markup, bookmarks, analytics, initialization, server sync

Scanner:
- Enhanced docs with manga/comic support
- Added 148-line comprehensive overview
- All formats documented (ebooks, comics, manga)

WebSocket:
- Comprehensive real-time sync API
- Messages, topics, authentication, examples

Documentation:
- Updated api-reference.md with all 122+ endpoints
- Updated index.md with new categories

Total: 36 new files, 6 modified files, 100% coverage
This commit is contained in:
2026-02-08 12:39:46 -05:00
parent d43bd9526b
commit c4607cd9b5
38 changed files with 2275 additions and 15 deletions
@@ -0,0 +1,48 @@
# Bulk Delete Books
Delete multiple media items at once.
**Endpoint**: `POST /api/books/bulk-delete`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| media_item_ids | array of UUID | Yes | Array of media item UUIDs to delete |
### Example Request
```json
{
"media_item_ids": [
"550e8400-e29b-41d4-a716-446655440001",
"660e8400-e29b-41d4-a716-446655440002",
"770e8400-e29b-41d4-a716-446655440003"
]
}
```
## Response (200 OK)
```json
{
"message": "Books deleted successfully",
"deleted_count": 3,
"failed_count": 0
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have permission |
| 404 | One or more media items not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
@@ -0,0 +1,71 @@
# Bulk Update Books
Update multiple media items at once.
**Endpoint**: `POST /api/books/bulk-update`
**Auth**: Required
**Content-Type**: `application/json`
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| media_item_ids | array of UUID | Yes | Array of media item UUIDs to update |
| updates | object | Yes | Fields to update (see below) |
### Update Fields
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| tags | array of strings | No | New tags (will replace existing) |
| contributors | array of strings | No | New contributors (will replace existing) |
| add_tags | array of strings | No | Tags to add to existing |
| remove_tags | array of strings | No | Tags to remove from existing |
### Example Request
```json
{
"media_item_ids": [
"550e8400-e29b-41d4-a716-446655440001",
"660e8400-e29b-41d4-a716-446655440002"
],
"updates": {
"add_tags": ["science-fiction", "award-winner"],
"contributors": ["Publisher Name"]
}
}
```
## Response (200 OK)
```json
{
"message": "Books updated successfully",
"updated_count": 2,
"failed_count": 0,
"normalized_tags": ["Science-Fiction", "Award-Winner"],
"normalized_contributors": ["Publisher Name"]
}
```
## Tag and Contributor Normalization
The backend automatically normalizes tags and contributors:
- **Tags**: Titlecased, punctuation preserved, deduplicated
- **Contributors**: Original casing preserved, punctuation preserved
- **Search fields**: Lowercase, no punctuation, stored in `tags_search` and `contributors_search`
## Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request data |
| 401 | Invalid or expired token |
| 403 | User does not have permission |
| 404 | One or more media items not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
+56
View File
@@ -0,0 +1,56 @@
# Download Book
Download a book file.
**Endpoint**: `GET /api/books/:uuid/download`
**Auth**: Not required (public endpoint)
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| uuid | string (UUID) | Yes | Media item UUID |
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| Authorization | string | No* | Bearer token (required if media item is not public) |
\* If the media item is in a non-public library, authentication is required.
### Example Request
```http
GET /api/books/550e8400-e29b-41d4-a716-446655440000/download
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Response (200 OK)
Binary file download with appropriate Content-Type header.
**Possible Content-Types:**
- application/epub+zip
- application/pdf
- application/x-mobipocket-ebook
- application/octet-stream
**Headers:**
```
Content-Type: application/epub+zip
Content-Disposition: attachment; filename="book-title.epub"
Content-Length: 1234567
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Authentication required for non-public content |
| 404 | Media item not found |
| 404 | Book file not found on disk |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->