john-okeefe
91c8be8562
Add koreader/resolve_book.md for GET /api/sync/koreader/resolve, list the endpoint in the API reference, and describe the resolve-then-pull- then-push linking flow in the KOReader protocol page — including why a device pushing to bootstrap its identity creates progress conflicts for books already mid-read from other sources.
51 lines
1.6 KiB
Markdown
51 lines
1.6 KiB
Markdown
# Resolve Book
|
|
|
|
Map a book's file SHA-256 to its Bookhoard UUID without touching progress
|
|
state. Used by devices to link a freshly downloaded book before their first
|
|
pull, so the device's first-page position is never pushed (which would
|
|
conflict with server-side progress for books already mid-read).
|
|
|
|
**Endpoint**: `GET /api/sync/koreader/resolve`
|
|
**Auth**: Required (Device authentication)
|
|
|
|
## Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --------- | ------ | -------- | ------------------------------------ |
|
|
| sha256 | string | Yes | File content hash (64 hex characters) |
|
|
|
|
Resolution is format-aware: the hash is checked against both
|
|
`media_items.file_sha256` and `media_item_formats.file_sha256`, so a
|
|
converted file (KEPUB/PDF) matches its media item too.
|
|
|
|
## Device Authentication
|
|
|
|
This endpoint requires device authentication (not user JWT). Devices
|
|
authenticate using their device credentials.
|
|
|
|
### Example Request
|
|
|
|
```http
|
|
GET /api/sync/koreader/resolve?sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
|
Authorization: Bearer {device_token}
|
|
```
|
|
|
|
## Response (200 OK)
|
|
|
|
```json
|
|
{
|
|
"book_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
|
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
|
"title": "Book Title",
|
|
"author": "Author Name"
|
|
}
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
| Code | Description |
|
|
| ---- | -------------------------------------------- |
|
|
| 400 | Missing or malformed `sha256` parameter |
|
|
| 401 | Device authentication failed |
|
|
| 404 | No book in the library matches the given hash |
|