docs: update comprehensive API documentation and project guides
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:
@@ -9,6 +9,7 @@ Complete API reference for collection management endpoints.
|
||||
## Overview
|
||||
|
||||
Collections allow you to organize your books into custom categories with:
|
||||
|
||||
- **Auto-assignment rules**: Automatically add books matching criteria
|
||||
- **View settings**: Per-device display preferences
|
||||
- **Shelf mappings**: Sync to device-specific shelves (Kobo, KOReader)
|
||||
@@ -24,6 +25,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Get all collections for the authenticated user
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"collections": [
|
||||
@@ -63,6 +65,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Create a new collection
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "To Read",
|
||||
@@ -90,6 +93,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
|
||||
- `name` (required): Collection name (max 255 chars)
|
||||
- `description` (optional): Collection description
|
||||
- `color` (optional): Hex color code (e.g., "#FF5733")
|
||||
@@ -98,6 +102,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
- `view_settings` (optional): Per-device display preferences
|
||||
|
||||
**Rule Object**:
|
||||
|
||||
- `field`: Field to match on (genre, author, series, language, publisher, copyright_year, tags)
|
||||
- `operator`: Comparison operator (equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than)
|
||||
- `value`: Value to compare against
|
||||
@@ -113,9 +118,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Get single collection with all books
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
@@ -144,9 +151,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Update collection details
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Request Body**: All fields are optional
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Sci-Fi Favorites",
|
||||
@@ -165,6 +174,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Delete a collection (books are NOT deleted)
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Response** (204 No Content)
|
||||
@@ -180,9 +190,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Add one or more books to a collection
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"book_ids": [
|
||||
@@ -202,6 +214,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Remove a single book from a collection
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
- `bookId`: Media Item UUID
|
||||
|
||||
@@ -214,9 +227,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Remove multiple books at once (efficient)
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"book_ids": [
|
||||
@@ -227,6 +242,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
```
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"removed": 2,
|
||||
@@ -243,13 +259,16 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Get all books in a collection
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Collection UUID
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
- `limit` (optional): Number of books to return (default: 50)
|
||||
- `offset` (optional): Number of books to skip (default: 0)
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"books": [
|
||||
@@ -276,6 +295,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Test which books would match given rules (without saving)
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"rules": [
|
||||
@@ -294,6 +314,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
```
|
||||
|
||||
**Supported Fields**:
|
||||
|
||||
- `genre`: Book genre
|
||||
- `author`: Book author
|
||||
- `series`: Book series name
|
||||
@@ -303,6 +324,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
- `tags`: Book tags
|
||||
|
||||
**Supported Operators**:
|
||||
|
||||
- `equals`: Exact match
|
||||
- `not_equals`: Not equal
|
||||
- `contains`: Contains substring (case-insensitive)
|
||||
@@ -313,6 +335,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
- `less_than`: Less than (numeric)
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"matches": [
|
||||
@@ -341,9 +364,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Get all collection-to-shelf mappings for a device
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `deviceId`: Device UUID
|
||||
|
||||
**Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": [
|
||||
@@ -366,9 +391,11 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Map a collection to a device shelf
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `deviceId`: Device UUID
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"collection_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
@@ -378,6 +405,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
```
|
||||
|
||||
**Sync Directions**:
|
||||
|
||||
- `bidirectional`: Sync both ways between Bookhoard and device
|
||||
- `book_to_hoard`: Bookhoard → Device only
|
||||
- `device_to_hoard`: Device → Bookhoard only
|
||||
@@ -392,10 +420,12 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Update existing shelf mapping
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `deviceId`: Device UUID
|
||||
- `collectionId`: Collection UUID
|
||||
|
||||
**Request Body**:
|
||||
|
||||
```json
|
||||
{
|
||||
"device_shelf_name": "Science Fiction",
|
||||
@@ -412,6 +442,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
**Description**: Remove shelf mapping
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `deviceId`: Device UUID
|
||||
- `collectionId`: Collection UUID
|
||||
|
||||
@@ -424,6 +455,7 @@ Collections allow you to organize your books into custom categories with:
|
||||
All endpoints may return these errors:
|
||||
|
||||
**400 Bad Request**:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "invalid request: validation failed"
|
||||
@@ -431,6 +463,7 @@ All endpoints may return these errors:
|
||||
```
|
||||
|
||||
**401 Unauthorized**:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "authentication required"
|
||||
@@ -438,6 +471,7 @@ All endpoints may return these errors:
|
||||
```
|
||||
|
||||
**404 Not Found**:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "collection not found"
|
||||
@@ -445,6 +479,7 @@ All endpoints may return these errors:
|
||||
```
|
||||
|
||||
**500 Internal Server Error**:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "internal server error"
|
||||
@@ -459,6 +494,7 @@ All endpoints may return these errors:
|
||||
- **Unauthenticated**: 10 requests per minute
|
||||
|
||||
Headers included:
|
||||
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
@@ -483,6 +519,7 @@ Complete API tests available in `bruno/collections/`:
|
||||
- `Bulk Remove Books.yml`
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
bruno run bruno/collections/
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user