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

docs: update comprehensive API documentation and project guides

Browse Source 
This commit updates all documentation files throughout the project:

- Updated IMPLEMENTATION_PLAN.md with new implementation details
- Updated PROJECT_GUIDELINES.md with coding standards and practices
- Updated README.md with current project information
- Updated SCREENSHOT_AUTOMATION.md with new automation details
- Added TEST_DATA.md with test fixtures data
- Updated cover_image_serving_plan.md with static URL patterns

Documentation API updates:
- Updated API reference documentation for all endpoints including:
  - Authentication (login, logout, register, refresh_token)
  - Book matching (auto_link, bulk_link, link_book, search)
  - Collections (CRUD operations, shelf mappings, auto-assign rules)
  - Conflicts (bulk operations, resolve/dismiss)
  - Devices (registration, approval, shelf management)
  - Highlights (create, update, delete, get)
  - Kobo sync (bookmark, markup, initialization, sync)
  - KOReader sync (library, metadata, bookmarks, progress)
  - Libraries (CRUD, folders, media items, stats)
  - Media items (bulk operations, CRUD)
  - Notes (CRUD operations)
  - OPDS (acquisition, feeds, publication)
  - Progress (reading progress tracking)
  - Queue (device queue management)
  - Ratings (star ratings)
  - Scanner (watch mode, scan operations)
  - Sync protocols (Kobo, KOReader)
  - Users (profile, password, admin operations)
  - WebSocket protocols

- Updated user guides (admin, dashboard, settings, sync)
- Updated device setup guides (Kobo, KOReader)
- Updated developer guides (testing, contributing, operations)
- Updated scripts/README.md
This commit is contained in:
john-okeefe
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer/api-reference.md
+64 -10
View File
@@ -4,6 +4,7 @@
> For updated, split endpoint documentation with interactive API explorer, see [API Documentation Portal](api/api-reference.md).
>
> **Use the split docs for:**
>
> - Easier navigation by category
> - Interactive API explorer
> - Endpoint-specific examples
@@ -65,6 +66,7 @@ Content-Type: application/json
```
**Response** (201):
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
@@ -93,6 +95,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
@@ -118,6 +121,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"token": "new-jwt-token",
@@ -144,6 +148,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"id": "uuid",
@@ -219,6 +224,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"libraries": [
@@ -290,11 +296,13 @@ Authorization: Bearer <token>
```
**Query Parameters**:
- `library_id` (required): UUID of library
- `limit`: Number of items to return (max 100, default 20)
- `offset`: Number of items to skip
**Response** (200):
```json
{
"media_items": [
@@ -337,11 +345,13 @@ Authorization: Bearer <token>
```
**Query Parameters**:
- `q` (required): Search query (minimum 2 characters)
- `limit`: Number of results (default 20)
- `offset`: Number to skip
**Response** (200):
```json
{
"results": [
@@ -409,6 +419,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"media_item_id": "uuid",
@@ -452,6 +463,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"sync_status": "success",
@@ -478,6 +490,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"notes": [
@@ -541,6 +554,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"highlights": [
@@ -611,6 +625,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"rating": 8,
@@ -668,6 +683,7 @@ Content-Type: application/json
```
**Response** (201):
```json
{
"device_id": "uuid",
@@ -690,6 +706,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"status": "pending|approved|expired",
@@ -711,6 +728,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"devices": [
@@ -760,10 +778,12 @@ 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,
@@ -782,6 +802,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"devices": [
@@ -805,9 +826,11 @@ Authorization: Bearer <token>
```
**Query Parameters**:
- `limit` (optional): Number of results (default: 10)
**Response** (200):
```json
{
"books": [
@@ -842,6 +865,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"matches": [
@@ -875,6 +899,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"results": [
@@ -904,6 +929,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"auto_linked": 15,
@@ -927,6 +953,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"unlinked_book_id": "uuid-1",
@@ -950,6 +977,7 @@ Authorization: Bearer <token>
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
@@ -960,6 +988,7 @@ For complete collection management documentation, see **[COLLECTIONS_API.md](COL
- `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
@@ -974,37 +1003,39 @@ 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"
<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"
<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"
<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>
@@ -1018,9 +1049,11 @@ 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"
@@ -1043,6 +1076,7 @@ GET /opds/devices/{deviceId}/formats/{bookId}
```
**Response** (200):
```json
{
"media_item_id": "uuid-123",
@@ -1109,6 +1143,7 @@ Content-Type: application/json
```
**Response** (202):
```json
{
"sync_status": "accepted",
@@ -1133,6 +1168,7 @@ Authorization: Bearer <device_token>
```
**Response** (200):
```json
{
"uuid": "book-uuid",
@@ -1186,6 +1222,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"Status": "Success",
@@ -1202,6 +1239,7 @@ Authorization: Bearer <device_token>
```
**Response** (200):
```json
{
"library_sync": [
@@ -1229,6 +1267,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"book_id": "book-uuid",
@@ -1307,10 +1346,12 @@ Authorization: Bearer <token>
```
**Query Parameters**:
- `status`: "unresolved|all" (default: "unresolved")
- `type`: "progress|note|highlight|all" (default: "all")
**Response** (200):
```json
{
"conflicts": [
@@ -1373,6 +1414,7 @@ Content-Type: application/json
```
**Response** (200):
```json
{
"conflict_resolved": true,
@@ -1408,6 +1450,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"items": [
@@ -1473,6 +1516,7 @@ Authorization: Bearer <token>
```
**Response** (200):
```json
{
"pending": 15,
@@ -1494,6 +1538,7 @@ WS /ws/sync?token=<token>
### Message Format
**Client → Server (Heartbeat)**:
```json
{
"type": "ping"
@@ -1501,6 +1546,7 @@ WS /ws/sync?token=<token>
```
**Server → Client (Progress Update)**:
```json
{
"type": "progress_update",
@@ -1523,6 +1569,7 @@ WS /ws/sync?token=<token>
```
**Server → Client (Conflict Detected)**:
```json
{
"type": "conflict",
@@ -1536,6 +1583,7 @@ WS /ws/sync?token=<token>
```
**Server → Client (Pong)**:
```json
{
"type": "pong"
@@ -1571,16 +1619,19 @@ All endpoints return standardized error responses:
### Rate Limiting
**Per-Device Limits**:
- Sync requests: 60/minute
- Progress updates: 120/minute
- Metadata requests: 30/minute
**Per-User Limits**:
- All requests: 300/minute
- Conflict resolutions: 10/minute
- Device registrations: 5/hour
**Rate Limit Headers**:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
@@ -1612,16 +1663,19 @@ bruno/
## Testing with Bruno OpenCollection YAML
Install Bruno CLI:
```bash
npm install -g @usebruno/cli
```
Run all tests:
```bash
bruno run
```
Run specific collection:
```bash
bruno run bruno/devices/
```