fix(docs): Work Order 2 — correct stale paths (11 docs + 3 Bruno)
Fix all wrong-path artifacts identified by the audit: - Kobo sync endpoints (init/bookmark/markup/sync-from-server/analytics): add missing :token device segment (6 doc files incl. kobo-protocol.md) - Highlights/notes update+delete: add missing /:id media-item prefix - media-items/download_media_item.md: removed (static /uploads route, not an API endpoint; info about the file route is recoverable from OPDS docs) - Bruno: /libraries/visible -> /visibility, /collections/books missing id, /audio/0 -> track_index - operations/troubleshooting.md: same /libraries/visible -> /visibility fix - media-items/get_audio_track.md + get_audio_chapters.md: /audio/0 examples fixed - Deleted monolithic docs/developer/api-reference.md (duplicate of split docs) - Fixed 4 stale entries in docs/developer/api/api-reference.md (split index) Audit re-run: orphan docs 0, orphan Bruno 6 (all scenario files with literal IDs).
This commit is contained in:
1 parent
cc893f758e
commit
50282895f5
19 files changed
+29
-1831
No files matched your search
@@ -1,48 +0,0 @@
|
||||
# Download Media Item
|
||||
|
||||
Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
|
||||
|
||||
Book files are served by the authenticated file route, the same one the web reader uses. Build the URL from the media item's `library_id` and relative `file_path` (both returned by the media item list/get endpoints):
|
||||
|
||||
**Endpoint**: `GET /uploads/library-{library_id}/{file_path}`
|
||||
**Auth**: Required (JWT - Bearer header or session cookie)
|
||||
|
||||
The `file_path` segments are URL-escaped individually; slashes are preserved. `cover_image_path` uses the same route.
|
||||
|
||||
## Path Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
| ----------- | ------ | -------- | ------------------------------------ |
|
||||
| library_id | string | Yes | Library UUID (the item's library) |
|
||||
| file_path | string | Yes | The item's relative `file_path` |
|
||||
|
||||
## Response
|
||||
|
||||
**Success (200 OK)**: Binary file data
|
||||
|
||||
**Response Headers**:
|
||||
|
||||
- `Content-Type`: MIME type by file extension (`application/epub+zip`, `application/pdf`, …; `application/octet-stream` fallback)
|
||||
- `Cache-Control`: `public, max-age=86400`
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
| ---- | --------------------------- |
|
||||
| 400 | Invalid library ID or path |
|
||||
| 401 | Missing/invalid token |
|
||||
| 404 | File not found on disk |
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -O -H "Authorization: Bearer $TOKEN" \
|
||||
"http://localhost:8765/uploads/library/550e8400-.../books/1984.epub"
|
||||
```
|
||||
|
||||
(URL shape: `/uploads/library-{uuid}/{escaped-relative-path}`.)
|
||||
|
||||
## Notes
|
||||
|
||||
- **Do not rely on `GET /api/media-items/:id/download`** — it appears in older docs but is **not registered**; `MediaHandler.DownloadBook` exists as dead code. Use the file route above.
|
||||
- OPDS-capable devices may alternatively use the device-authenticated `GET /opds/devices/{deviceId}/download/{bookId}`, which supports on-the-fly format conversion (epub, kepub, pdf, cbz).
|
||||
@@ -23,7 +23,7 @@ which file model produced them.
|
||||
"tracks": [
|
||||
{
|
||||
"index": 0,
|
||||
"url": "/api/media-items/{id}/audio/0",
|
||||
"url": "/api/media-items/{id}/audio/{trackIndex}",
|
||||
"title": "01 First",
|
||||
"path": "Author/Title/01 First.mp3",
|
||||
"start": 0.0,
|
||||
|
||||
@@ -40,5 +40,5 @@ answers **403** on every track (same gate as the download endpoint).
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
-H "Range: bytes=0-1023" \
|
||||
"http://localhost:8765/api/media-items/550e8400-.../audio/0"
|
||||
"http://localhost:8765/api/media-items/550e8400-.../audio/{track_index}"
|
||||
```
|
||||
Reference in new issue
Block a user