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

docs(api): add WebSocket real-time sync API documentation

Browse Source 
- sync_api.md - Comprehensive WebSocket API guide

Covers:
- Connection and authentication (JWT + device)
- Client→Server messages (subscribe, ping)
- Server→Client messages (progress, conflicts, scan status, etc.)
- Message formats with examples
- Connection lifecycle
- Topics: progress, conflicts, scanner, devices, queue
- JavaScript usage example with reconnection
- Best practices for heartbeat and error handling

Documents bidirectional real-time sync API
This commit is contained in:
john-okeefe
2026-02-08 12:38:50 -05:00
parent bab78c6c85
commit d43bd9526b
4 changed files with 246 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer/api/koreader/get_library.md
+53
View File
@@ -0,0 +1,53 @@
# Get Library
Get library metadata for KOReader device.
**Endpoint**: `GET /api/sync/koreader/library`
**Auth**: Required (Device authentication)
## Device Authentication
This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| X-Device-ID | string | Yes | Device UUID |
| X-Device-Key | string | Yes | Device authentication key |
### Example Request
```http
GET /api/sync/koreader/library
X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
X-Device-Key: device-auth-key
```
## Response (200 OK)
```json
{
"books": [
{
"id": "uuid",
"title": "Book Title",
"authors": ["Author Name"],
"file": "book.epub",
"size": 1234567
}
],
"total": 42
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Device authentication failed |
| 404 | Device not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/developer/api/koreader/get_metadata.md
+55
View File
@@ -0,0 +1,55 @@
# Get Metadata
Get metadata for a book from KOReader device.
**Endpoint**: `GET /api/sync/koreader/metadata/:uuid`
**Auth**: Required (Device authentication)
## Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|-----------|-------------|
| uuid | string (UUID) | Yes | Book UUID |
## Device Authentication
This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
## Request Headers
| Header | Type | Required | Description |
|--------|------|-----------|-------------|
| X-Device-ID | string | Yes | Device UUID |
| X-Device-Key | string | Yes | Device authentication key |
### Example Request
```http
GET /api/sync/koreader/metadata/550e8400-e29b-41d4-a716-446655440000
X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
X-Device-Key: device-auth-key
```
## Response (200 OK)
```json
{
"id": "uuid",
"title": "Book Title",
"authors": ["Author Name"],
"path": "/path/to/book.epub",
"file_size": 1234567,
"modified_at": "2026-02-08T10:00:00Z"
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Device authentication failed |
| 404 | Book or device not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/developer/api/koreader/sync_bookmarks.md
+71
View File
@@ -0,0 +1,71 @@
# Sync Bookmarks
Sync bookmarks from KOReader device.
**Endpoint**: `POST /api/sync/koreader/bookmarks`
**Auth**: Required (Device authentication)
## Device Authentication
This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| device_id | string (UUID) | Yes | Device UUID |
| bookmarks | array | Yes | Array of bookmark objects |
### Bookmark Object
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| book | string | Yes | Book identifier |
| chapter | string | No | Chapter title |
| page | integer | No | Page number |
| position | float | Yes | Position in document (0-1) |
| notes | string | No | Bookmark notes |
| highlighted_text | string | No | Highlighted text |
| time | string | Yes | ISO 8601 timestamp |
| created_at | string | Yes | ISO 8601 timestamp |
### Example Request
```json
{
"device_id": "550e8400-e29b-41d4-a716-446655440000",
"bookmarks": [
{
"book": "book.epub",
"chapter": "Chapter 1",
"page": 25,
"position": 0.125,
"notes": "Important section",
"highlighted_text": "Text to remember",
"time": "2026-02-08T10:00:00Z",
"created_at": "2026-02-08T10:00:00Z"
}
]
}
```
## Response (200 OK)
```json
{
"message": "Bookmarks synced successfully",
"synced_count": 1
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Device authentication failed |
| 400 | Invalid request data |
| 404 | Device not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->
docs/developer/api/koreader/sync_progress.md
+67
View File
@@ -0,0 +1,67 @@
# Sync Progress
Sync reading progress from KOReader device.
**Endpoint**: `POST /api/sync/koreader/progress`
**Auth**: Required (Device authentication)
## Device Authentication
This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
## Request Body
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| device_id | string (UUID) | Yes | Device UUID |
| progress | array | Yes | Array of progress objects |
### Progress Object
| Field | Type | Required | Description |
|--------|------|-----------|-------------|
| book | string | Yes | Book identifier (filename or UUID) |
| percent | float | Yes | Progress percentage (0-100) |
| page | integer | No | Current page number |
| total_pages | integer | No | Total pages in document |
| date_read | string | No | ISO 8601 timestamp of last read |
| updated_at | string | Yes | ISO 8601 timestamp |
### Example Request
```json
{
"device_id": "550e8400-e29b-41d4-a716-446655440000",
"progress": [
{
"book": "book.epub",
"percent": 75.5,
"page": 150,
"total_pages": 200,
"date_read": "2026-02-08T10:00:00Z",
"updated_at": "2026-02-08T10:00:00Z"
}
]
}
```
## Response (200 OK)
```json
{
"message": "Progress synced successfully",
"synced_count": 1
}
```
## Error Responses
| Code | Description |
|------|-------------|
| 401 | Device authentication failed |
| 400 | Invalid request data |
| 404 | Device not found |
## Try It Out
<!-- API Explorer will be inserted here in Phase 3 -->