docs: update references for new configuration structure
- Update README.md with simplified documentation links - Update docs/API_REFERENCE.md formatting and structure - Update docs/SYNC_USER_GUIDE.md with minor improvements These updates reflect the reorganized documentation structure and new configuration approach with defaults in docker-compose.yml.
This commit is contained in:
+327
-6
@@ -12,12 +12,16 @@ Complete API documentation for Bookhoard v1.0 with Universal Cross-Platform Sync
|
||||
6. [Notes & Highlights](#notes--highlights)
|
||||
7. [Ratings](#ratings)
|
||||
8. [Device Management](#device-management)
|
||||
9. [Sync Protocol - KOReader](#sync-protocol---koreader)
|
||||
10. [Sync Protocol - Kobo](#sync-protocol---kobo)
|
||||
11. [Universal Progress](#universal-progress)
|
||||
12. [Conflicts](#conflicts)
|
||||
13. [Sync Queue](#sync-queue)
|
||||
14. [WebSocket](#websocket)
|
||||
9. [Analytics](#analytics)
|
||||
10. [Book Matching & Linking](#book-matching--linking)
|
||||
11. [Collections](#collections) → See [COLLECTIONS_API.md](COLLECTIONS_API.md)
|
||||
12. [OPDS](#opds-open-publication-distribution-system)
|
||||
13. [Sync Protocol - KOReader](#sync-protocol---koreader)
|
||||
14. [Sync Protocol - Kobo](#sync-protocol---kobo)
|
||||
15. [Universal Progress](#universal-progress)
|
||||
16. [Conflicts](#conflicts)
|
||||
17. [Sync Queue](#sync-queue)
|
||||
18. [WebSocket](#websocket)
|
||||
|
||||
## Base URL
|
||||
|
||||
@@ -735,6 +739,323 @@ DELETE /api/devices/{device_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## Analytics
|
||||
|
||||
### Get Reading Statistics
|
||||
|
||||
```http
|
||||
GET /api/analytics/reading-stats?start_date={date}&end_date={date}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `start_date` (optional): Start date (ISO 8601 format)
|
||||
- `end_date` (optional): End date (ISO 8601 format)
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"pages_read": 1250,
|
||||
"books_completed": 5,
|
||||
"reading_time_hours": 42.5,
|
||||
"sessions_count": 28,
|
||||
"average_session_minutes": 91
|
||||
}
|
||||
```
|
||||
|
||||
### Get Device Usage Statistics
|
||||
|
||||
```http
|
||||
GET /api/analytics/device-usage
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"device_id": "uuid",
|
||||
"device_name": "My Kobo Clara",
|
||||
"device_type": "kobo",
|
||||
"sync_count": 145,
|
||||
"last_sync": "2026-02-01T10:00:00Z",
|
||||
"pages_synced": 890
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Get Popular Books
|
||||
|
||||
```http
|
||||
GET /api/analytics/popular-books?limit={limit}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `limit` (optional): Number of results (default: 10)
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"books": [
|
||||
{
|
||||
"media_item_id": "uuid",
|
||||
"title": "Book Title",
|
||||
"author": "Author Name",
|
||||
"cover_image_path": "/covers/book.jpg",
|
||||
"read_count": 15,
|
||||
"average_rating": 8.5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Book Matching & Linking
|
||||
|
||||
### Query Books for Matching
|
||||
|
||||
```http
|
||||
POST /api/sync/books/query
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"identifiers": ["isbn:978-0345391802", "uuid:abc-123"],
|
||||
"sha256": "a1b2c3d4e5f6abc123...",
|
||||
"title": "The Hobbit",
|
||||
"author": "J.R.R. Tolkien",
|
||||
"file_size": 2456789
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"matches": [
|
||||
{
|
||||
"media_item_id": "uuid-123",
|
||||
"bookhoard_uuid": "uuid-123",
|
||||
"confidence": 1.0,
|
||||
"match_method": "uuid_match"
|
||||
}
|
||||
],
|
||||
"action": "auto_link"
|
||||
}
|
||||
```
|
||||
|
||||
### Bulk Link Books
|
||||
|
||||
```http
|
||||
POST /api/sync/bulk-link-books
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"links": [
|
||||
{
|
||||
"unlinked_book_id": "uuid-1",
|
||||
"media_item_id": "uuid-2",
|
||||
"confidence_score": 1.0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"unlinked_book_id": "uuid-1",
|
||||
"status": "success",
|
||||
"media_item_id": "uuid-2"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"failed": 0
|
||||
}
|
||||
```
|
||||
|
||||
### Auto-Link Books
|
||||
|
||||
```http
|
||||
POST /api/sync/auto-link-books
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"confidence_threshold": 0.8,
|
||||
"limit": 50
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"auto_linked": 15,
|
||||
"results": [
|
||||
{
|
||||
"unlinked_book_id": "uuid-1",
|
||||
"title": "The Hobbit",
|
||||
"matched_media_item_id": "uuid-2",
|
||||
"confidence": 0.95,
|
||||
"match_method": "sha256_match"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Get Unlinked Book Suggestions
|
||||
|
||||
```http
|
||||
GET /api/sync/unlinked-books/{id}/suggestions
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"unlinked_book_id": "uuid-1",
|
||||
"title_from_device": "The Hobbit",
|
||||
"sha256": "",
|
||||
"suggestions": [
|
||||
{
|
||||
"media_item_id": "uuid-2",
|
||||
"bookhoard_uuid": "uuid-2",
|
||||
"confidence": 0.95,
|
||||
"match_method": "sha256_match"
|
||||
}
|
||||
],
|
||||
"total_suggestions": 1,
|
||||
"action": "auto_link"
|
||||
}
|
||||
```
|
||||
|
||||
## Collections
|
||||
|
||||
For complete collection management documentation, see **[COLLECTIONS_API.md](COLLECTIONS_API.md)**.
|
||||
|
||||
**Quick Reference**:
|
||||
- `GET /api/collections` - List all collections
|
||||
- `POST /api/collections` - Create new collection
|
||||
- `GET /api/collections/{id}` - Get collection details
|
||||
- `PUT /api/collections/{id}` - Update collection
|
||||
- `DELETE /api/collections/{id}` - Delete collection
|
||||
- `POST /api/collections/test-rules` - Test auto-assign rules
|
||||
- `POST /api/collections/bulk-add-books` - Bulk add books to collections
|
||||
- `GET /api/collections/{id}/books` - Get books in collection
|
||||
|
||||
**Features**:
|
||||
- Auto-assign rules based on genre, author, series, tags, language, publisher, year
|
||||
- Device shelf mappings (Kobo shelves, KOReader categories)
|
||||
- Test rules before applying
|
||||
- Bulk book operations
|
||||
|
||||
## OPDS (Open Publication Distribution System)
|
||||
|
||||
### Get Device Catalog
|
||||
|
||||
```http
|
||||
GET /opds/devices/{deviceId}/catalog?page={page}&per_page={per_page}
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `page` (optional): Page number (default: 1)
|
||||
- `per_page` (optional): Items per page (default: 50, max: 200)
|
||||
|
||||
**Response** (200 - OPDS 1.2 XML):
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<feed xmlns="http://www.w3.org/2005/Atom"
|
||||
xmlns:opds="http://opds-spec.org/2010/"
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/">
|
||||
<id>urn:uuid:device-id</id>
|
||||
<title>Bookhoard Library</title>
|
||||
<updated>2026-02-01T12:00:00Z</updated>
|
||||
|
||||
<link rel="self" href="http://localhost:8765/opds/devices/kobo-id/catalog"/>
|
||||
<link rel="search" href="http://localhost:8765/opds/devices/kobo-id/search"/>
|
||||
<link rel="start" href="http://localhost:8765/opds/devices/kobo-id/nav"/>
|
||||
|
||||
<entry>
|
||||
<id>urn:uuid:bookhoard-uuid-123</id>
|
||||
<dc:title>The Hobbit</dc:title>
|
||||
<dc:creator>J.R.R. Tolkien</dc:creator>
|
||||
<updated>2026-02-01T10:00:00Z</updated>
|
||||
|
||||
<link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123"
|
||||
type="application/epub+zip"
|
||||
rel="http://opds-spec.org/acquisition/open-access"/>
|
||||
|
||||
<link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123?format=kepub"
|
||||
type="application/vnd.kobo+xml+zip"
|
||||
rel="alternate"/>
|
||||
|
||||
<dc:identifier id="bookhoard">uuid-123</dc:identifier>
|
||||
<meta property="bookhoard:sha256">abc123...</meta>
|
||||
</entry>
|
||||
</feed>
|
||||
```
|
||||
|
||||
### Download Book with Format Conversion
|
||||
|
||||
```http
|
||||
GET /opds/devices/{deviceId}/download/{bookId}?format={format}
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `format` (optional): Book format - `epub` (default), `kepub`
|
||||
|
||||
**Response** (200):
|
||||
- Headers:
|
||||
- `Content-Type`: `application/epub+zip` or `application/vnd.kobo+xml+zip`
|
||||
- `Content-Disposition`: attachment; filename="The Hobbit.epub"
|
||||
- `X-Bookhoard-UUID`: uuid-123
|
||||
- `X-Bookhoard-SHA256`: abc123... (original hash)
|
||||
- `X-Bookhoard-KEPUB-SHA256`: xyz789... (KEPUB hash if format=kepub)
|
||||
|
||||
### Search OPDS Catalog
|
||||
|
||||
```http
|
||||
GET /opds/devices/{deviceId}/search?q={query}
|
||||
```
|
||||
|
||||
**Response** (200 - OPDS 1.2 XML with search results)
|
||||
|
||||
### List Available Formats
|
||||
|
||||
```http
|
||||
GET /opds/devices/{deviceId}/formats/{bookId}
|
||||
```
|
||||
|
||||
**Response** (200):
|
||||
```json
|
||||
{
|
||||
"media_item_id": "uuid-123",
|
||||
"formats": [
|
||||
{
|
||||
"format_type": "epub",
|
||||
"file_path": "/path/to/book.epub",
|
||||
"file_sha256": "abc123...",
|
||||
"file_size_bytes": 2456789,
|
||||
"mime_type": "application/epub+zip",
|
||||
"available": true
|
||||
},
|
||||
{
|
||||
"format_type": "kepub",
|
||||
"file_path": "/cache/book.kepub.epub",
|
||||
"file_sha256": "xyz789...",
|
||||
"file_size_bytes": 2478932,
|
||||
"mime_type": "application/vnd.kobo+xml+zip",
|
||||
"available": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Sync Protocol - KOReader
|
||||
|
||||
### KOReader Progress Sync
|
||||
|
||||
Reference in New Issue
Block a user