refactor(bruno): reorganize file structure from bruno-yaml to flat bruno directory
- Move all files from bruno-yaml/* to bruno/* - Maintains existing directory structure within categories - Updates bruno/user/auth files with OAuth2 refresh token flow - Updates bruno/user/profile files for user profile management - Adds bruno/dashboard/ directory with dashboard API tests - Preserves all existing test scenarios and OpenCollection YAML format - No functional changes - file reorganization only
This commit is contained in:
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Get Admin Library
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/admin/library'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Admin Library Page
|
||||
|
||||
Retrieves the admin library page for administrative access.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /admin/library
|
||||
|
||||
**Headers:**
|
||||
- `Authorization` (string): Bearer token
|
||||
|
||||
**Response:**
|
||||
- HTML content for the admin library page
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
@@ -0,0 +1,39 @@
|
||||
info:
|
||||
name: Get Admin Profile
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/admin/profile'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Admin Profile
|
||||
|
||||
Retrieves the admin profile information for administrative access.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /admin/profile
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Response:**
|
||||
- JSON object containing admin profile details
|
||||
- `id` (string): Admin user ID
|
||||
- `email` (string): Admin email
|
||||
- `username` (string): Admin username
|
||||
- `theme` (string): Theme preference
|
||||
- `first_name` (string): First name
|
||||
- `last_name` (string): Last name
|
||||
- `is_admin` (boolean): Admin status
|
||||
- `created_at` (string): Account creation timestamp
|
||||
- `updated_at` (string): Last update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (non-admin users)
|
||||
- 404: Profile not found
|
||||
@@ -0,0 +1,47 @@
|
||||
info:
|
||||
name: Get Device Usage
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/device-usage'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get usage statistics for all devices.
|
||||
|
||||
**Endpoint**: GET /api/analytics/device-usage
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| devices | array | List of device usage statistics |
|
||||
| devices[].id | string | Device ID |
|
||||
| devices[].device_name | string | Device name |
|
||||
| devices[].device_type | string | Device type (kobo, kindle, koreader) |
|
||||
| devices[].sync_count | int | Number of sync operations |
|
||||
| devices[].last_sync | string | Last sync timestamp |
|
||||
| devices[].total_reading_minutes | int | Total reading time on device |
|
||||
| devices[].books_read | int | Number of books completed on device |
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"id": "789e4567-e89b-12d3-a456-426614174001",
|
||||
"device_name": "My Kobo Clara",
|
||||
"device_type": "kobo",
|
||||
"sync_count": 45,
|
||||
"last_sync": "2026-02-08T17:25:00Z",
|
||||
"total_reading_minutes": 1250,
|
||||
"books_read": 3
|
||||
@@ -0,0 +1,57 @@
|
||||
info:
|
||||
name: Get Popular Books
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/popular-books?limit=10'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get popular books sorted by read count.
|
||||
|
||||
**Endpoint**: GET /api/analytics/popular-books
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| limit | int | No | Maximum number of books to return (default: 10) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| books | array | List of popular books |
|
||||
| books[].media_item_id | string | Book ID |
|
||||
| books[].title | string | Book title |
|
||||
| books[].author | string | Book author |
|
||||
| books[].read_count | int | Number of times read |
|
||||
| books[].avg_completion | float | Average completion rate (0-1) |
|
||||
| books[].cover_url | string | Cover image URL |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/popular-books?limit=10
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"books": [
|
||||
{
|
||||
"media_item_id": "323e4567-e89b-12d3-a456-426614174002",
|
||||
"title": "The Great Gatsby",
|
||||
"author": "F. Scott Fitzgerald",
|
||||
"read_count": 5,
|
||||
"avg_completion": 0.85,
|
||||
"cover_url": "/api/books/323e4567-e89b-12d3-a456-426614174002/cover"
|
||||
@@ -0,0 +1,58 @@
|
||||
info:
|
||||
name: Get Reading Stats Date Range
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/reading-stats?start_date=2024-01-01&end_date=2024-01-31'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get reading statistics for a specific date range.
|
||||
|
||||
**Endpoint**: GET /api/analytics/reading-stats
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| start_date | string | No | Start date (ISO 8601 format, default: 30 days ago) |
|
||||
| end_date | string | No | End date (ISO 8601 format, default: today) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| total_books_read | int | Total books completed in range |
|
||||
| total_pages_read | int | Total pages read in range |
|
||||
| total_reading_time_minutes | int | Total reading time in minutes |
|
||||
| completion_rate | float | Percentage of books completed (0-1) |
|
||||
| daily_reading_minutes | array | Daily reading time per day |
|
||||
| daily_reading_minutes[].date | string | Date (ISO 8601) |
|
||||
| daily_reading_minutes[].minutes | int | Minutes read on that date |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/reading-stats?start_date=2024-01-01&end_date=2024-01-31
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"total_books_read": 2,
|
||||
"total_pages_read": 450,
|
||||
"total_reading_time_minutes": 720,
|
||||
"completion_rate": 0.85,
|
||||
"daily_reading_minutes": [
|
||||
{
|
||||
"date": "2024-01-01",
|
||||
"minutes": 30
|
||||
@@ -0,0 +1,58 @@
|
||||
info:
|
||||
name: Get Reading Stats
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/reading-stats'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get overall reading statistics for the authenticated user.
|
||||
|
||||
**Endpoint**: GET /api/analytics/reading-stats
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| start_date | string | No | Start date (ISO 8601 format) |
|
||||
| end_date | string | No | End date (ISO 8601 format) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| total_books_read | int | Total books completed |
|
||||
| total_pages_read | int | Total pages read |
|
||||
| total_reading_time_minutes | int | Total reading time in minutes |
|
||||
| completion_rate | float | Average book completion rate (0-1) |
|
||||
| daily_reading_minutes | array | Daily reading time breakdown |
|
||||
| daily_reading_minutes[].date | string | Date (ISO 8601) |
|
||||
| daily_reading_minutes[].minutes | int | Minutes read on that date |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/reading-stats
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"total_books_read": 12,
|
||||
"total_pages_read": 3450,
|
||||
"total_reading_time_minutes": 5400,
|
||||
"completion_rate": 0.78,
|
||||
"daily_reading_minutes": [
|
||||
{
|
||||
"date": "2026-01-15",
|
||||
"minutes": 45
|
||||
@@ -0,0 +1,50 @@
|
||||
info:
|
||||
name: Bulk Delete Media Items
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/media-items/bulk-delete'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"media_item_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Delete Media Items
|
||||
|
||||
Deletes multiple media items in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/media-items/bulk-delete
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `media_item_ids` (array of strings): Array of media item UUIDs to delete
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each deletion attempt
|
||||
- `total` (number): Total number of media items processed
|
||||
- `deleted` (number): Number of successfully deleted media items
|
||||
- `failed` (number): Number of failed deletions
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"media_item_ids": [
|
||||
"uuid-1",
|
||||
"uuid-2",
|
||||
"uuid-3"
|
||||
]
|
||||
@@ -0,0 +1,55 @@
|
||||
info:
|
||||
name: Bulk Update Media Items
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/media-items/bulk-update'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"media_item_updates\": [\n {\n \"media_item_id\"\
|
||||
: \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Update Media Items
|
||||
|
||||
Updates multiple media items in a single request with different fields for each item.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/media-items/bulk-update
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `media_item_updates` (array): Array of update objects
|
||||
- `media_item_id` (string): Media item UUID to update
|
||||
- `updates` (object): Fields to update (can include title, author, genre, tags, contributors, etc.)
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each update attempt
|
||||
- `total` (number): Total number of media items processed
|
||||
- `updated` (number): Number of successfully updated media items
|
||||
- `failed` (number): Number of failed updates
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"media_item_updates": [
|
||||
{
|
||||
"media_item_id": "uuid-1",
|
||||
"updates": {
|
||||
"title": "New Title",
|
||||
"genre": "Fiction",
|
||||
"tags": ["fiction", "adventure"]
|
||||
@@ -0,0 +1,11 @@
|
||||
info:
|
||||
name: Add Books to Collection
|
||||
type: http
|
||||
seq: 6
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{book_id_1"
|
||||
@@ -0,0 +1,15 @@
|
||||
info:
|
||||
name: Create Collection
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"name\": \"Science Fiction\",\n \"description\": \"My favorite\
|
||||
\ sci-fi books\",\n \"color\": \"#ff0000\",\n \"icon\": \"\U0001F680\"\
|
||||
,\n \"auto_assign_rules\": [\n {\n \"id\": \"rule-1\",\n \
|
||||
\ \"field\": \"genre\",\n \"operator\": \"equals\",\n \"value\"\
|
||||
: \"Science Fiction\",\n \"priority\": 8"
|
||||
@@ -0,0 +1,11 @@
|
||||
info:
|
||||
name: Create Device Mapping
|
||||
type: http
|
||||
seq: 9
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"collection_id\": \"{{collection_id"
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Delete Collection
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Delete Device Mapping
|
||||
type: http
|
||||
seq: 11
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{mapping_id}}'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Get Book Collections
|
||||
type: http
|
||||
seq: 12
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/books/{{book_id}}'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Get Collection
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Get Collections
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections?include_auto=true&sort_by=name'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Get Device Mappings
|
||||
type: http
|
||||
seq: 8
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,8 @@
|
||||
info:
|
||||
name: Remove Book from Collection
|
||||
type: http
|
||||
seq: 7
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/{{book_id}}'
|
||||
auth: inherit
|
||||
@@ -0,0 +1,15 @@
|
||||
info:
|
||||
name: Update Collection
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"name\": \"Sci-Fi Favorites\",\n \"description\": \"Updated\
|
||||
\ description\",\n \"color\": \"#00ff00\",\n \"icon\": \"⭐\",\n \"\
|
||||
auto_assign_rules\": [\n {\n \"id\": \"rule-2\",\n \"field\"\
|
||||
: \"series\",\n \"operator\": \"equals\",\n \"value\": \"Foundation\"\
|
||||
,\n \"priority\": 9"
|
||||
@@ -0,0 +1,12 @@
|
||||
info:
|
||||
name: Update Device Mapping
|
||||
type: http
|
||||
seq: 10
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{mapping_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_shelf_name\": \"Science Fiction\",\n \"sync_direction\"\
|
||||
: \"book_to_device\""
|
||||
@@ -0,0 +1,53 @@
|
||||
info:
|
||||
name: Bulk Add Books to Collections
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/bulk-add-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"operations\": [\n {\n \"collection_id\": \"{{collectionId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Add Books to Collections
|
||||
|
||||
Adds multiple books to multiple collections in a single request. Each operation specifies a collection and a list of books to add.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/bulk-add-books
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `operations` (array): Array of collection-book operations
|
||||
- `collection_id` (string): Collection UUID
|
||||
- `book_ids` (array): Array of book UUIDs to add to the collection
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each operation
|
||||
- `total` (number): Total number of operations
|
||||
- `success` (number): Number of successful operations
|
||||
- `failed` (number): Number of failed operations
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"operations": [
|
||||
{
|
||||
"collection_id": "collection-uuid-1",
|
||||
"book_ids": ["book-1", "book-2"]
|
||||
@@ -0,0 +1,23 @@
|
||||
info:
|
||||
name: Bulk Remove Books - All Books
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books from Collection
|
||||
|
||||
Removes multiple books from a collection in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id
|
||||
@@ -0,0 +1,27 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Empty List
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": []"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Empty List Validation
|
||||
|
||||
Tests validation behavior when providing an empty book_ids array.
|
||||
|
||||
**Expected Result:** 400 Bad Request
|
||||
|
||||
**Validation Rule:** book_ids array must contain at least one book UUID.
|
||||
|
||||
**Purpose:** Ensures the API properly validates input and rejects empty removal requests.
|
||||
@@ -0,0 +1,31 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Invalid IDs
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Invalid IDs
|
||||
|
||||
Tests behavior when the book_ids array contains invalid UUID formats or non-existent books.
|
||||
|
||||
**Expected Result:** 200 OK with partial success
|
||||
|
||||
**Purpose:** Verifies that:
|
||||
- Invalid UUID formats don't crash the endpoint
|
||||
- Non-existent book IDs are handled gracefully
|
||||
- Valid IDs in the same request are still processed
|
||||
- Response includes detailed results showing which succeeded/failed
|
||||
|
||||
**Note:** The endpoint should process all valid IDs and report failures for invalid ones, allowing clients to handle partial failures appropriately.
|
||||
@@ -0,0 +1,27 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Single Book
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Single Book
|
||||
|
||||
Tests that bulk remove endpoint works correctly with a single book.
|
||||
|
||||
**Expected Result:** 200 OK with removed: 1, total: 1
|
||||
|
||||
**Purpose:** Verifies the bulk remove endpoint handles single-item arrays correctly, providing flexibility for clients to use the same endpoint for both single and multiple removals.
|
||||
|
||||
**Note:** Using bulk remove for a single book is functionally equivalent to the single remove endpoint but allows for consistent error handling and response format.
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Test Collection Rules - Author Contains
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"author\",\n \
|
||||
\ \"operator\": \"contains\",\n \"value\": \"Asimov\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Author Contains
|
||||
|
||||
Tests the "contains" operator on the author field to find books by a specific author (partial match).
|
||||
|
||||
**Example Use Case:** Finding all books by an author whose name contains "Asimov" (e.g., "Isaac Asimov").
|
||||
|
||||
**Operator:** `contains` - Matches if the field contains the specified value as a substring (case-insensitive typically).
|
||||
|
||||
**Expected Result:** Returns all books where the author field contains "Asimov".
|
||||
|
||||
**Purpose:** Demonstrates text-based partial matching for author searches, useful when you don't need the exact author name or want to find books by authors with similar names.
|
||||
@@ -0,0 +1,32 @@
|
||||
info:
|
||||
name: Test Collection Rules - Copyright Year Greater Than
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"copyright_year\"\
|
||||
,\n \"operator\": \"greater_than\",\n \"value\": \"2000\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Copyright Year Greater Than
|
||||
|
||||
Tests the "greater_than" operator on the copyright_year field to find books published after a specific year.
|
||||
|
||||
**Example Use Case:** Creating a "Modern Books" collection with books published after 2000.
|
||||
|
||||
**Operator:** `greater_than` - Matches if the field value is greater than the specified value (numeric comparison).
|
||||
|
||||
**Field:** `copyright_year` - The year the book was copyrighted/published.
|
||||
|
||||
**Expected Result:** Returns all books with copyright_year greater than 2000 (i.e., published in 2001 or later).
|
||||
|
||||
**Purpose:** Demonstrates numeric comparison operators for creating date-based collections, useful for organizing books by publication era.
|
||||
@@ -0,0 +1,29 @@
|
||||
info:
|
||||
name: Test Collection Rules - Empty Rules Array
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": []"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Empty Rules Array
|
||||
|
||||
Tests validation behavior when providing an empty rules array.
|
||||
|
||||
**Expected Result:** 400 Bad Request
|
||||
|
||||
**Validation Rule:** rules array must contain at least one rule object.
|
||||
|
||||
**Purpose:** Ensures the API properly validates input and rejects empty rule sets, preventing accidental queries that would return all books or cause performance issues.
|
||||
|
||||
**Use Case:** Client-side validation should prevent sending empty rules, but the API should also validate to catch malformed requests.
|
||||
@@ -0,0 +1,34 @@
|
||||
info:
|
||||
name: Test Collection Rules - No Matches
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"genre\",\n \
|
||||
\ \"operator\": \"equals\",\n \"value\": \"NonExistentGenre123456\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - No Matches
|
||||
|
||||
Tests behavior when collection rules don't match any books in the library.
|
||||
|
||||
**Example Use Case:** Validating that a new genre name doesn't exist before creating a collection for it, or testing edge cases.
|
||||
|
||||
**Expected Result:** 200 OK with empty matches array and total: 0
|
||||
|
||||
**Purpose:** Verifies that the API handles zero-match scenarios gracefully:
|
||||
- Returns 200 (success) not 404
|
||||
- Returns empty array, not null
|
||||
- Returns total: 0 for clarity
|
||||
- No errors thrown for no results
|
||||
|
||||
**Note:** An empty result set is a valid response and doesn't indicate an error. This allows users to test rules confidently before creating collections.
|
||||
@@ -0,0 +1,67 @@
|
||||
info:
|
||||
name: Test Collection Rules
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"genre\",\n \
|
||||
\ \"operator\": \"equals\",\n \"value\": \"Science Fiction\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules
|
||||
|
||||
Tests collection rules against the library to see which books match, without creating a collection. Useful for previewing what books would be included in a collection with specific rules.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/test-rules
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `rules` (array): Array of rule objects to test
|
||||
- `field` (string): Field to test (genre, author, copyright_year, tags, etc.)
|
||||
- `operator` (string): Comparison operator
|
||||
- `equals`: Exact match
|
||||
- `contains`: Contains substring (for text fields)
|
||||
- `greater_than`: Greater than (for numeric fields)
|
||||
- `less_than`: Less than (for numeric fields)
|
||||
- `not_equals`: Not equal to
|
||||
- `starts_with`: Starts with
|
||||
- `ends_with`: Ends with
|
||||
- `is_empty`: Field is empty or null
|
||||
- `is_not_empty`: Field is not empty and not null
|
||||
- `value` (string): Value to compare against (not required for is_empty/is_not_empty)
|
||||
|
||||
**Response:**
|
||||
- `matches` (array): Array of matching books
|
||||
- `id` (string): Book UUID
|
||||
- `title` (string): Book title
|
||||
- `author` (string): Book author
|
||||
- `genre` (string): Book genre
|
||||
- Additional book metadata
|
||||
- `total` (number): Total number of matching books
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success - returns matching books
|
||||
- 400: Invalid request (empty rules array, invalid field/operator)
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Request:**
|
||||
```json
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"field": "genre",
|
||||
"operator": "equals",
|
||||
"value": "Science Fiction"
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Delete Conflict
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Delete Conflict
|
||||
|
||||
Permanently deletes a specific conflict record from the system.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -0,0 +1,37 @@
|
||||
info:
|
||||
name: Dismiss All Resolved Conflicts
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/dismiss-all'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Dismiss All Resolved Conflicts
|
||||
|
||||
Deletes all resolved conflicts for the authenticated user, cleaning up the conflict list.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/dismiss-all
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Response:**
|
||||
- `deleted` (number): Number of conflict records that were deleted
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success - conflicts deleted
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"deleted": 5
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Get Conflict Details
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Get Conflict Details
|
||||
|
||||
Retrieves detailed information about a specific conflict, including side-by-side comparison of conflicting data from all sources.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -0,0 +1,74 @@
|
||||
info:
|
||||
name: List Conflicts
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts?status=unresolved'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## List Conflicts
|
||||
|
||||
Lists all sync conflicts for the authenticated user with optional filtering.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/conflicts
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string, optional): Filter by resolution status
|
||||
- `unresolved`: Only unresolved conflicts (default)
|
||||
- `user_resolved`: Conflicts resolved by user
|
||||
- `auto_resolved`: Automatically resolved conflicts
|
||||
- `all`: All conflicts regardless of status
|
||||
- `type` (string, optional): Filter by conflict type
|
||||
- `progress`: Reading progress conflicts
|
||||
- `note`: Bookmark/note conflicts
|
||||
- `highlight`: Highlight conflicts
|
||||
|
||||
**Response:**
|
||||
- `conflicts` (array): Array of conflict objects
|
||||
- `total` (number): Total number of conflicts matching filters
|
||||
- `unresolved` (number): Number of unresolved conflicts
|
||||
|
||||
**Each Conflict Object:**
|
||||
- `id` (string): Conflict UUID
|
||||
- `media_item_id` (string): Associated book UUID
|
||||
- `media_item_title` (string): Book title
|
||||
- `conflict_type` (string): Type of conflict (progress, note, highlight)
|
||||
- `conflict_data` (object): Side-by-side comparison of conflicting data
|
||||
- `koreader`: Data from KOReader device
|
||||
- `kobo`: Data from Kobo device
|
||||
- `web`: Data from web interface
|
||||
- `resolution_status` (string): Current status (unresolved, user_resolved, auto_resolved)
|
||||
- `created_at` (string): ISO 8601 timestamp when conflict was detected
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Request:**
|
||||
```
|
||||
GET /api/conflicts?status=unresolved&type=progress
|
||||
```
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"conflicts": [
|
||||
{
|
||||
"id": "conflict-uuid",
|
||||
"media_item_id": "book-uuid",
|
||||
"media_item_title": "Foundation",
|
||||
"conflict_type": "progress",
|
||||
"conflict_data": {
|
||||
"koreader": { "percentage": 0.65, "epubcfi": "..."
|
||||
@@ -0,0 +1,25 @@
|
||||
info:
|
||||
name: Resolve Conflict
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}/resolve'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"winner\": \"koreader\",\n \"manual_data\": null,\n \"\
|
||||
apply_to_all_future_conflicts\": false,\n \"reason\": \"User chose more recent\
|
||||
\ progress\""
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Resolve Conflict
|
||||
|
||||
Resolves a sync conflict by choosing which source to use for the conflicting data.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -0,0 +1,49 @@
|
||||
info:
|
||||
name: Bulk Dismiss Conflicts
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/bulk-dismiss'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"conflict_ids\": [\n \"{{conflictId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Dismiss Conflicts
|
||||
|
||||
Dismisses multiple sync conflicts without resolving them. This removes them from the conflict list while leaving the data unchanged.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/bulk-dismiss
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `conflict_ids` (array): Array of conflict UUIDs to dismiss
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each dismissal
|
||||
- `total` (number): Total number of conflicts processed
|
||||
- `success` (number): Number of successfully dismissed conflicts
|
||||
- `failed` (number): Number of failed dismissals
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: One or more conflicts not found
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"conflict_ids": ["uuid-1", "uuid-2"]
|
||||
@@ -0,0 +1,55 @@
|
||||
info:
|
||||
name: Bulk Resolve Conflicts
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/bulk-resolve'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"conflict_ids\": [\n \"{{conflictId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Resolve Conflicts
|
||||
|
||||
Resolves multiple sync conflicts in a single request using a specified resolution strategy.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/bulk-resolve
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `conflict_ids` (array): Array of conflict UUIDs to resolve
|
||||
- `strategy` (string): Resolution strategy
|
||||
- `most_recent`: Use the most recently updated progress
|
||||
- `highest_progress`: Use the reading progress with the highest percent read
|
||||
- `server`: Always prefer server-side data
|
||||
- `device`: Always prefer device-side data
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each conflict resolution
|
||||
- `total` (number): Total number of conflicts processed
|
||||
- `success` (number): Number of successfully resolved conflicts
|
||||
- `failed` (number): Number of failed resolutions
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: One or more conflicts not found
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"conflict_ids": ["uuid-1", "uuid-2", "uuid-3"],
|
||||
"strategy": "most_recent"
|
||||
@@ -0,0 +1,46 @@
|
||||
info:
|
||||
name: Bulk Resolve with Highest Progress Strategy
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/bulk-resolve'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"conflict_ids\": [\n \"{{conflictId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Resolve with Highest Progress Strategy
|
||||
|
||||
Resolves multiple sync conflicts using the "highest_progress" strategy, which keeps the reading progress with the highest percentage read.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/bulk-resolve
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `conflict_ids` (array): Array of conflict UUIDs to resolve
|
||||
- `strategy` (string): Must be "highest_progress"
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each conflict resolution
|
||||
- `total` (number): Total number of conflicts processed
|
||||
- `success` (number): Number of successfully resolved conflicts
|
||||
- `failed` (number): Number of failed resolutions
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** The highest progress strategy is ideal when you want to preserve the most reading progress across devices. Use this when you've been reading on multiple devices and want to keep the furthest position.
|
||||
@@ -0,0 +1,38 @@
|
||||
info:
|
||||
name: Create Collection with Dashboard
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"creates collection successfully\", function() {\n expect(res.status).to.eql(201);"
|
||||
|
||||
docs: |-
|
||||
Create a new collection with dashboard visibility enabled.
|
||||
|
||||
**Endpoint**: POST /api/collections
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| name | string | Yes | Collection name |
|
||||
| description | string | No | Collection description |
|
||||
| color | string | No | Hex color code |
|
||||
| icon | string | No | Icon emoji or name |
|
||||
| show_on_dashboard | boolean | No | Show on dashboard (default: false) |
|
||||
|
||||
## Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Favorites",
|
||||
"description": "My favorite books",
|
||||
"color": "#FF5733",
|
||||
"icon": "⭐",
|
||||
"show_on_dashboard": true
|
||||
@@ -0,0 +1,52 @@
|
||||
info:
|
||||
name: Get Dashboard Sections
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/dashboard/sections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200 with auth\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get all dashboard sections for a specific library.
|
||||
|
||||
**Endpoint**: GET /api/dashboard/sections
|
||||
**Auth**: Required (Bearer token via auth: inherit)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| library_id | string | Yes | Library UUID |
|
||||
|
||||
## Response
|
||||
|
||||
Returns array of sections including:
|
||||
- Smart sections (continue-reading, in-progress, recently-added, etc.)
|
||||
- User collections marked with show_on_dashboard: true
|
||||
|
||||
## Section Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| smart | Auto-generated sections based on user activity |
|
||||
| collection | User-created collections with dashboard enabled |
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"sections": [
|
||||
{
|
||||
"id": "continue-reading",
|
||||
"type": "smart",
|
||||
"title": "Continue Reading",
|
||||
"icon": "📖",
|
||||
"items": [...],
|
||||
"view_all_url": "/section/continue-reading"
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Get Dashboard Sections by Library
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/dashboard/sections'
|
||||
auth: inherit
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get all dashboard sections for a specific library.
|
||||
|
||||
**Endpoint**: GET /api/dashboard/sections
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| library_id | string | Yes | Library UUID |
|
||||
|
||||
## Response
|
||||
|
||||
Returns array of sections including:
|
||||
- Smart sections (continue-reading, in-progress, recently-added, etc.)
|
||||
- User collections marked for dashboard
|
||||
@@ -0,0 +1,17 @@
|
||||
info:
|
||||
name: Update Collection Dashboard Visibility
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"updates collection successfully\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Update collection settings including dashboard visibility.
|
||||
|
||||
**Endpoint**: PUT /api/collections/{id
|
||||
@@ -0,0 +1,36 @@
|
||||
info:
|
||||
name: Update Dashboard Preferences
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/dashboard/preferences'
|
||||
auth: inherit
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200 with valid request\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Update dashboard preferences for the authenticated user.
|
||||
|
||||
**Endpoint**: POST /api/dashboard/preferences
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| library_id | string | Yes | Library UUID |
|
||||
| hidden_sections | array | No | Section IDs to hide |
|
||||
| section_order | array | No | Section IDs in custom order |
|
||||
| items_per_section | int | No | Items to show per section (10-50) |
|
||||
|
||||
## Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
|
||||
"hidden_sections": ["recently-added"],
|
||||
"section_order": ["continue-reading", "in-progress"],
|
||||
"items_per_section": 25
|
||||
@@ -0,0 +1,7 @@
|
||||
info:
|
||||
name: Bookhoard Device Management API
|
||||
type: collection
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
@@ -0,0 +1,96 @@
|
||||
info:
|
||||
name: Get Analytics Tests
|
||||
type: http
|
||||
seq: 7
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/v1/analytics/gettests'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
platform: android
|
||||
firmware_version: 4.30.19023
|
||||
|
||||
docs: |-
|
||||
## Get Kobo Analytics Tests
|
||||
|
||||
Retrieves A/B testing configuration and feature flags for Kobo device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/v1/analytics/gettests
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `platform` (string): Device platform
|
||||
- `android`: Kobo Android app
|
||||
- `kobo`: Native Kobo firmware
|
||||
- `firmware_version` (string): Firmware version (e.g., "4.30.19023")
|
||||
- `device_model` (string, optional): Device model identifier
|
||||
- `locale` (string, optional): Device locale (e.g., "en_US")
|
||||
|
||||
**Response:**
|
||||
- `tests` (array): Active A/B tests
|
||||
- `test_name` (string): Test identifier
|
||||
- `variant` (string): Assigned variant (A, B, C, etc.)
|
||||
- `enabled` (boolean): Whether test is active
|
||||
- `parameters` (object): Test-specific parameters
|
||||
- `features` (object): Feature flags
|
||||
- `feature_name` (boolean/string): Feature state
|
||||
- `configuration` (object): Device configuration
|
||||
- `sync_interval_minutes` (integer): Recommended sync frequency
|
||||
- `batch_size` (integer): Max items per batch sync
|
||||
- `timeout_seconds` (integer): Request timeout
|
||||
- `version` (string): Configuration version
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid request parameters
|
||||
|
||||
**Analytics Testing Purpose:**
|
||||
- Kobo uses A/B testing for UX features
|
||||
- Feature flags for gradual rollout
|
||||
- Performance monitoring configuration
|
||||
- Sync behavior optimization
|
||||
- Device-specific tuning
|
||||
|
||||
**Common Tests:**
|
||||
- Sync frequency optimization
|
||||
- UI/UX variations
|
||||
- Network usage patterns
|
||||
- Battery life improvements
|
||||
- Feature set variations by model
|
||||
|
||||
**Feature Flags:**
|
||||
- New sync features
|
||||
- Beta functionality
|
||||
- Platform-specific capabilities
|
||||
- Experimental features
|
||||
|
||||
**Configuration Parameters:**
|
||||
- Optimal sync intervals for device
|
||||
- Batch size limits based on device capabilities
|
||||
- Timeout values for network conditions
|
||||
- Retry logic configuration
|
||||
- Cache policy settings
|
||||
|
||||
**Usage:**
|
||||
- Called during device initialization
|
||||
- Refreshed daily or weekly
|
||||
- Cached on device
|
||||
- Affects sync behavior
|
||||
- Can be overridden by server
|
||||
|
||||
**Use Cases:**
|
||||
- Device initialization
|
||||
- Feature rollout testing
|
||||
- Performance optimization
|
||||
- UX experiment participation
|
||||
- Configuration management
|
||||
@@ -0,0 +1,81 @@
|
||||
info:
|
||||
name: Get Kobo Library
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/kobo/library'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Kobo Library
|
||||
|
||||
Retrieves the user's Kobo library metadata for device sync.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/kobo/library
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Query Parameters:**
|
||||
None (returns entire library)
|
||||
|
||||
**Response:**
|
||||
- `books` (array): Library items
|
||||
- `ContentId` (string): Unique book identifier
|
||||
- `Title` (string): Book title
|
||||
- `Author` (string): Author name
|
||||
- `Publisher` (string): Publisher name
|
||||
- `Description` (string): Book description
|
||||
- `ISBN` (string, optional): ISBN-13
|
||||
- `PublicationDate` (string): Release date
|
||||
- `EntitlementId` (string): Kobo entitlement ID
|
||||
- `CrossRevisionId` (string): Revision identifier
|
||||
- `MimeType` (string): Content type (application/epub+zip)
|
||||
- `FileSize` (integer): File size in bytes
|
||||
- `CoverImageId` (string): Cover image identifier
|
||||
- `DownloadUrls` (object): Download URLs
|
||||
- `download_url` (string): Direct download link
|
||||
- `download_acquisition_url` (string): OPDS acquisition URL
|
||||
- `sync_metadata` (object):
|
||||
- `last_sync` (string): Last library sync timestamp
|
||||
- `total_books` (integer): Total book count
|
||||
- `has_updates` (boolean): Whether updates are available
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Device not approved
|
||||
|
||||
**Library Sync Purpose:**
|
||||
- Kobo device needs to know available books
|
||||
- Enables download via device browser
|
||||
- Provides metadata for device display
|
||||
- Supports Kobo's "My Books" feature
|
||||
- Enables on-device purchasing integration
|
||||
|
||||
**Kobo Device Usage:**
|
||||
- Device fetches library on registration
|
||||
- Refreshed daily or on manual sync
|
||||
- User can browse library on device
|
||||
- Books downloaded wirelessly to device
|
||||
- Supports "Buy on Kobo, read on device" workflow
|
||||
|
||||
**Authentication Methods:**
|
||||
This endpoint uses **Bearer token authentication** (token in Authorization header).
|
||||
Alternative: Use `/sync/kobo/{token}/library` with token in URL path.
|
||||
|
||||
**Performance:**
|
||||
- Typical response: 50-200KB for 100 books
|
||||
- Processing time: 200-800ms
|
||||
- Cache duration: 5 minutes
|
||||
- Pagination available for large libraries (>500 books)
|
||||
|
||||
**Use Cases:**
|
||||
- Initial device registration
|
||||
- Library refresh on device
|
||||
- Book discovery on device
|
||||
- Download link generation
|
||||
- Metadata sync for OPDS
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Get Unlinked Book Suggestions
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/sync/unlinked-books/{{unlinkedBookId}}/suggestions'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Get Unlinked Book Suggestions
|
||||
|
||||
Retrieves suggested media items from the library that match an unlinked book, enabling manual linking.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /sync/unlinked-books/{unlinkedBookId
|
||||
@@ -0,0 +1,7 @@
|
||||
info:
|
||||
name: Bookhoard Kobo Sync API
|
||||
type: collection
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
@@ -0,0 +1,45 @@
|
||||
info:
|
||||
name: Auto-Link Unlinked Books
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/sync/auto-link-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"confidence_threshold\": 0.8,\n \"limit\": 50"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Auto-Link Unlinked Books
|
||||
|
||||
Automatically links unlinked books to media items based on title and author matching with a configurable confidence threshold.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /sync/auto-link-books
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `confidence_threshold` (number, optional): Minimum confidence score for auto-linking (0-1, default: 0.8)
|
||||
- `limit` (number, optional): Maximum number of books to auto-link (default: 50)
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each auto-link attempt
|
||||
- `total` (number): Total number of books processed
|
||||
- `success` (number): Number of successful links
|
||||
- `failed` (number): Number of failed links
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** Higher confidence thresholds produce fewer but more accurate matches. Consider the tradeoff between automation and accuracy.
|
||||
@@ -0,0 +1,47 @@
|
||||
info:
|
||||
name: Bulk Link Unlinked Books
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/sync/bulk-link-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"links\": [\n {\n \"unlinked_book_id\": \"{{unlinkedBookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Link Unlinked Books
|
||||
|
||||
Links multiple unlinked books to media items in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /sync/bulk-link-books
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `links` (array): Array of link objects
|
||||
- `unlinked_book_id` (string): Unlinked book UUID
|
||||
- `media_item_id` (string): Media item UUID to link to
|
||||
- `confidence_score` (number): Match confidence (0-1)
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each link attempt
|
||||
- `total` (number): Total number of links processed
|
||||
- `success` (number): Number of successful links
|
||||
- `failed` (number): Number of failed links
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** Use this endpoint after reviewing suggestions from the Get Unlinked Book Suggestions endpoint.
|
||||
@@ -0,0 +1,98 @@
|
||||
info:
|
||||
name: Kobo Initialization
|
||||
type: http
|
||||
seq: 8
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/kobo/v1/initialization'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Kobo Device Initialization
|
||||
|
||||
Initializes Kobo device sync session and returns device configuration.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/kobo/v1/initialization
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Query Parameters:**
|
||||
- `Platform` (string, optional): Device platform (android, kobo)
|
||||
- `FirmwareVersion` (string, optional): Firmware version string
|
||||
- `Model` (string, optional): Device model name
|
||||
|
||||
**Response:**
|
||||
- `device` (object): Device information
|
||||
- `device_id` (string): Server device ID
|
||||
- `approved` (boolean): Whether device is approved
|
||||
- `sync_enabled` (boolean): Whether sync is active
|
||||
- `last_sync` (string): Last successful sync timestamp
|
||||
- `user` (object): User information
|
||||
- `user_id` (string): User identifier
|
||||
- `email` (string): User email (masked)
|
||||
- `library_size` (integer): Number of books in library
|
||||
- `sync_config` (object): Sync configuration
|
||||
- `sync_interval_minutes` (integer): Recommended sync frequency
|
||||
- `batch_size` (integer): Max items per batch
|
||||
- `timeout_seconds` (integer): Request timeout
|
||||
- `retry_count` (integer): Max retry attempts
|
||||
- `features` (object): Available features
|
||||
- `annotation_sync` (boolean): Annotation support
|
||||
- `bookmark_sync` (boolean): Bookmark support
|
||||
- `progress_sync` (boolean): Progress tracking
|
||||
- `library_download` (boolean): Library access
|
||||
- `endpoints` (object): API endpoint URLs
|
||||
- `markup_sync` (string): Progress/annotation sync URL
|
||||
- `bookmark_sync` (string): Bookmark sync URL
|
||||
- `library` (string): Library access URL
|
||||
- `sync_from_server` (string): Download sync URL
|
||||
- `server_time` (string): Current server timestamp
|
||||
- `version` (string): API version
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized (invalid token)
|
||||
- 403: Forbidden (device not approved)
|
||||
- 404: Device not found
|
||||
|
||||
**Initialization Flow:**
|
||||
1. Device powers on or connects to network
|
||||
2. Device calls initialization endpoint
|
||||
3. Server returns configuration and capabilities
|
||||
4. Device adjusts sync behavior based on config
|
||||
5. Device begins sync operations
|
||||
|
||||
**Authentication Methods:**
|
||||
This endpoint uses **Bearer token authentication** (token in Authorization header).
|
||||
Alternative: Use `/sync/kobo/{token}/v1/initialization` with token in URL path.
|
||||
|
||||
**Configuration Caching:**
|
||||
- Response cached on device for 24 hours
|
||||
- Refreshed on device reboot
|
||||
- Updated when sync settings change
|
||||
- Can be force-refreshed via device settings
|
||||
|
||||
**Device Approval:**
|
||||
- New devices: `approved: false`
|
||||
- Pending devices see limited functionality
|
||||
- Approval required for full sync
|
||||
- User approves via web interface
|
||||
- Re-initialization after approval
|
||||
|
||||
**Use Cases:**
|
||||
- Device registration
|
||||
- Daily device wakeup
|
||||
- Post-approval initialization
|
||||
- Configuration refresh
|
||||
- Feature capability check
|
||||
- Sync endpoint discovery
|
||||
|
||||
**Kobo Native Integration:**
|
||||
- Called by Kobo Nickel UI
|
||||
- Integrated with Kobo sync service
|
||||
- Part of Kobo account setup
|
||||
- Supports Kobo "Sync now" feature
|
||||
- Enables Kobo library browsing
|
||||
@@ -0,0 +1,53 @@
|
||||
info:
|
||||
name: Sync from Bookhoard to Kobo
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{baseURL}}/api/sync/kobo/sync-from-server'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "[\n {\n \"ContentId\": \"{{bookUUID"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{koboToken
|
||||
|
||||
docs: |-
|
||||
## Sync from Bookhoard to Kobo
|
||||
|
||||
Server-initiated sync pushing progress, bookmarks, and highlights from Bookhoard to Kobo device. Two-way sync endpoint.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/sync-from-server
|
||||
|
||||
**Authentication:** Bearer token with Kobo device identification
|
||||
|
||||
**Headers:**
|
||||
- `x-kobo-device` (string): JSON string containing Kobo device info
|
||||
- `DeviceId`: Kobo device ID
|
||||
- `Model`: Kobo device model
|
||||
- `SerialNumber`: Kobo device serial number
|
||||
|
||||
**Request Body:** Array of sync data objects
|
||||
- `ContentId` (string): Book UUID
|
||||
- `PercentRead` (number): Reading progress percentage (0-100)
|
||||
- `LastModified` (string): ISO 8601 timestamp
|
||||
- `Bookmarks` (array, optional): Array of bookmark objects
|
||||
- `BookmarkId`: Unique bookmark ID
|
||||
- `ContentId`: Book UUID
|
||||
- `BookmarkText`: Bookmark text/note
|
||||
- `BookmarkType`: Type (bookmark, annotation, etc.)
|
||||
- `BookmarkTitle`: Bookmark title
|
||||
- `Highlights` (array, optional): Array of highlight objects (same structure as bookmarks)
|
||||
|
||||
**Response:**
|
||||
- Sync result confirmation
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** Allows Bookhoard server to push updates to Kobo device, including reading progress, bookmarks, and highlights.
|
||||
@@ -0,0 +1,106 @@
|
||||
info:
|
||||
name: Sync Books from Server to Kobo
|
||||
type: http
|
||||
seq: 9
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/sync-from-server'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
force_sync: true
|
||||
books:
|
||||
- book-uuid-1
|
||||
- book-uuid-2
|
||||
|
||||
docs: |-
|
||||
## Sync Books from Server to Kobo
|
||||
|
||||
Pulls reading progress, annotations, and bookmarks from server to Kobo device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/sync-from-server
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `force_sync` (boolean): Force full sync (ignore last sync time)
|
||||
- `books` (array, optional): List of book UUIDs to sync
|
||||
- If empty, syncs all books with server data
|
||||
- If specified, only syncs listed books
|
||||
- `sync_options` (object, optional):
|
||||
- `since_date` (string): ISO 8601 timestamp for incremental sync
|
||||
- `include_annotations` (boolean): Include highlights/notes
|
||||
- `include_progress` (boolean): Include reading progress
|
||||
- `conflict_resolution` (string): `most_recent`, `server_wins`, `client_wins`
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Number of books synced
|
||||
- `skipped` (integer): Books with no server changes
|
||||
- `failed` (integer): Books that failed to sync
|
||||
- `results` (array): Per-book sync results
|
||||
- `book_id` (string): Book UUID
|
||||
- `status` (string): `synced`, `skipped`, `failed`
|
||||
- `progress_pulled` (boolean): Whether progress was downloaded
|
||||
- `annotations_pulled` (integer): Number of annotations downloaded
|
||||
- `error` (string, optional): Error message if failed
|
||||
- `server_timestamp` (string): Server timestamp of sync
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Sync completed
|
||||
- 207: Multi-status (some succeeded, some failed)
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid request
|
||||
|
||||
**Sync Direction:**
|
||||
- **Server → Device** (this endpoint)
|
||||
- Device → Server: Use `/sync/kobo/markup` endpoint
|
||||
- Bidirectional sync achieved by calling both
|
||||
|
||||
**Pull Sync Use Cases:**
|
||||
- New device setup (download all progress)
|
||||
- Device replacement (restore from server)
|
||||
- Multi-device sync (pull changes from other devices)
|
||||
- Conflict resolution (server wins)
|
||||
- Manual "Download from server" operation
|
||||
|
||||
**Conflict Resolution:**
|
||||
- `most_recent`: Latest timestamp wins (default)
|
||||
- `server_wins`: Server data always used
|
||||
- `client_wins`: Device data preserved
|
||||
- Applied per-book, per-item
|
||||
|
||||
**Sync Optimization:**
|
||||
- Incremental sync by default (since last sync)
|
||||
- Force sync does full comparison
|
||||
- Book-level batching (10 books per batch)
|
||||
- Delta transfer (only changed items)
|
||||
- Compression for large annotation sets
|
||||
|
||||
**Kobo Device Behavior:**
|
||||
- Device updates local database
|
||||
- Progress reflected in reading view
|
||||
- Annotations appear in Notebook
|
||||
- Bookmarks updated in navigation
|
||||
- Conflict warnings shown to user
|
||||
- Sync progress displayed on screen
|
||||
|
||||
**Performance:**
|
||||
- Small sync (1-10 books): 2-5 seconds
|
||||
- Medium sync (10-50 books): 5-15 seconds
|
||||
- Large sync (50-200 books): 15-45 seconds
|
||||
- Timeout: 120 seconds
|
||||
|
||||
**Use Cases:**
|
||||
- Initial device sync
|
||||
- After firmware update
|
||||
- From another device's changes
|
||||
- Manual sync request
|
||||
- Conflict recovery
|
||||
- Data restoration
|
||||
@@ -0,0 +1,91 @@
|
||||
info:
|
||||
name: Sync Multiple Books Progress
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/markup'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: x-kobo-device
|
||||
value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Aura"}'
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
ReadingSync:
|
||||
- ContentId: book-1-uuid
|
||||
PercentRead: 25.0
|
||||
EntitlementId: entitlement-1
|
||||
RemainingTimeMinutes: 240
|
||||
FirstReadTime: '2026-01-25T10:00:00Z'
|
||||
LastModified: '2026-01-30T18:00:00Z'
|
||||
- ContentId: book-2-uuid
|
||||
PercentRead: 78.5
|
||||
EntitlementId: entitlement-2
|
||||
RemainingTimeMinutes: 45
|
||||
FirstReadTime: '2026-01-25T14:00:00Z'
|
||||
LastModified: '2026-01-30T20:00:00Z'
|
||||
BookmarkSync: []
|
||||
|
||||
docs: |-
|
||||
## Sync Multiple Books Progress
|
||||
|
||||
Synchronizes reading progress for multiple books in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/markup
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Headers:**
|
||||
- `Authorization`: Bearer {{kobo_device_token}}
|
||||
- `x-kobo-device`: Device information (Model: "Kobo Aura")
|
||||
|
||||
**Request Body:**
|
||||
- `ReadingSync` (array): Multiple progress items
|
||||
- Each item contains: ContentId, PercentRead, EntitlementId, etc.
|
||||
- `BookmarkSync` (array): Empty for progress-only batch
|
||||
|
||||
**Response:**
|
||||
- `total` (integer): Total items in request
|
||||
- `synced` (integer): Successfully synced
|
||||
- `failed` (integer): Failed items
|
||||
- `results` (array): Per-item results
|
||||
- `ContentId` (string): Book UUID
|
||||
- `status` (string): `synced`, `failed`, `skipped`
|
||||
- `error` (string, optional): Error message if failed
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Batch sync completed
|
||||
- 207: Multi-status (some succeeded, some failed)
|
||||
- 401: Unauthorized
|
||||
- 413: Payload too large (>1MB)
|
||||
|
||||
**Batch Sync Advantages:**
|
||||
- Efficient sync of entire library
|
||||
- Reduces HTTP overhead
|
||||
- Faster for devices with many books
|
||||
- Atomic operation (all or nothing by default)
|
||||
|
||||
**Kobo Batch Sync Behavior:**
|
||||
- Triggered when device connects after being offline
|
||||
- Occurs during manual "Sync now" operation
|
||||
- Limited to 100 books per request
|
||||
- Progress updates shown on device
|
||||
- Failed items retried individually
|
||||
|
||||
**Performance:**
|
||||
- Typical batch: 10-50 books in 1-3 seconds
|
||||
- Large batch: 50-100 books in 3-8 seconds
|
||||
- Timeout: 30 seconds
|
||||
- Rate limit: 10 batches per minute per device
|
||||
|
||||
**Use Cases:**
|
||||
- Initial device sync after registration
|
||||
- Catch-up sync after extended offline period
|
||||
- Library-wide progress update
|
||||
- Pre-sync before device firmware update
|
||||
@@ -0,0 +1,84 @@
|
||||
info:
|
||||
name: Sync Progress with Bookmarks
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/markup'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: x-kobo-device
|
||||
value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
ReadingSync:
|
||||
- ContentId: book-uuid
|
||||
PercentRead: 42.3
|
||||
EntitlementId: entitlement-id
|
||||
RemainingTimeMinutes: 138
|
||||
FirstReadTime: '2026-01-25T10:00:00Z'
|
||||
LastModified: '2026-01-30T20:00:00Z'
|
||||
BookmarkSync:
|
||||
- ContentId: book-uuid
|
||||
BookmarkText: highlighted text passage
|
||||
BookmarkType: annotation
|
||||
BookmarkTitle: Chapter 3
|
||||
|
||||
docs: |-
|
||||
## Sync Progress with Bookmarks
|
||||
|
||||
Synchronizes reading progress and highlights/annotations from Kobo device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/markup
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Headers:**
|
||||
- `Authorization`: Bearer {{kobo_device_token}}
|
||||
- `x-kobo-device`: Device information JSON
|
||||
|
||||
**Request Body:**
|
||||
- `ReadingSync` (array): Progress items (see Sync Reading Progress)
|
||||
- `BookmarkSync` (array): Highlights and annotations
|
||||
- `ContentId` (string): Book UUID
|
||||
- `BookmarkText` (string): Highlighted text or note content
|
||||
- `BookmarkType` (string): Type of bookmark
|
||||
- `annotation`: Highlighted text
|
||||
- `note`: Personal note
|
||||
- `bookmark`: Location bookmark
|
||||
- `BookmarkTitle` (string): Reference (e.g., chapter name)
|
||||
- `ChapterID` (string, optional): Chapter identifier
|
||||
- `DateCreated` (string, optional): Creation timestamp
|
||||
|
||||
**Response:**
|
||||
- `progress_synced` (integer): Progress items synced
|
||||
- `bookmarks_synced` (integer): Bookmark items synced
|
||||
- `conflicts_resolved` (integer): Number of conflicts auto-resolved
|
||||
- `timestamp` (string): Sync timestamp
|
||||
- `details` (object): Sync breakdown by type
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Successful sync
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid data
|
||||
|
||||
**Kobo Highlight Features:**
|
||||
- 5 highlight colors (yellow, green, blue, pink, orange)
|
||||
- Chapter-based organization
|
||||
- Linked to reading progress
|
||||
- Appears in Kobo "Notebook" view
|
||||
- Can be exported from device
|
||||
- Syncs across all user devices
|
||||
|
||||
**Annotation Sync:**
|
||||
- Highlight text preserved exactly
|
||||
- Color mapped to system colors
|
||||
- Chapter reference maintained
|
||||
- Location data converted to standard format
|
||||
- Notes attached to highlights synced separately
|
||||
@@ -0,0 +1,84 @@
|
||||
info:
|
||||
name: Sync Reading Progress
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/markup'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: x-kobo-device
|
||||
value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
ReadingSync:
|
||||
- ContentId: book-uuid-here
|
||||
PercentRead: 45.6
|
||||
EntitlementId: entitlement-id-here
|
||||
RemainingTimeMinutes: 120
|
||||
FirstReadTime: '2026-01-25T10:00:00Z'
|
||||
LastModified: '2026-01-30T20:00:00Z'
|
||||
BookmarkSync: []
|
||||
|
||||
docs: |-
|
||||
## Sync Kobo Reading Progress
|
||||
|
||||
Synchronizes reading progress from a Kobo device to the server using Bearer token authentication.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/markup
|
||||
|
||||
**Authentication:** Bearer token (in Authorization header)
|
||||
|
||||
**Headers:**
|
||||
- `Authorization`: Bearer {{kobo_device_token}}
|
||||
- `x-kobo-device`: JSON-encoded device info
|
||||
- `DeviceId`: Kobo device identifier
|
||||
- `Model`: Device model (e.g., "Kobo Clara", "Kobo Libra", "Kobo Aura")
|
||||
|
||||
**Request Body:**
|
||||
- `ReadingSync` (array): Reading progress items
|
||||
- `ContentId` (string): Book/Content UUID
|
||||
- `PercentRead` (number): Reading progress 0-100
|
||||
- `EntitlementId` (string): Kobo entitlement ID
|
||||
- `RemainingTimeMinutes` (integer): Estimated reading time remaining
|
||||
- `FirstReadTime` (string): ISO 8601 timestamp when first opened
|
||||
- `LastModified` (string): ISO 8601 timestamp of last progress update
|
||||
- `BookmarkSync` (array): Empty array for progress-only sync
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Number of items synced
|
||||
- `failed` (integer): Number of items that failed to sync
|
||||
- `timestamp` (string): Server timestamp of sync
|
||||
- `books` (array): Synced book data
|
||||
- `ContentId` (string): Book UUID
|
||||
- `status` (string): `synced`, `failed`, `skipped`
|
||||
- `server_percent` (number): Server-side progress (for conflict detection)
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Sync successful
|
||||
- 401: Invalid device token
|
||||
- 403: Device not approved
|
||||
- 400: Invalid request format
|
||||
|
||||
**Authentication Methods:**
|
||||
This endpoint uses **Bearer token authentication** (token in Authorization header).
|
||||
Alternative: Use `/sync/kobo/{token}/markup` with token in URL path.
|
||||
|
||||
**Kobo Sync Features:**
|
||||
- Native Kobo sync protocol
|
||||
- Supports Kobo Clara, Libra, Aura, Forma, Sage, Elipsa
|
||||
- Progress percentage tracking
|
||||
- Reading time estimation
|
||||
- Cross-device synchronization
|
||||
- Automatic conflict resolution (most recent wins)
|
||||
|
||||
**Sync Frequency:**
|
||||
- Kobo devices auto-sync every 15-30 minutes when connected to WiFi
|
||||
- Manual sync available from device settings
|
||||
- Sync triggers on: device wake, book close, WiFi connection
|
||||
@@ -0,0 +1,92 @@
|
||||
info:
|
||||
name: Sync Single Bookmark
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/bookmark'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: x-kobo-device
|
||||
value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
ContentId: book-uuid
|
||||
BookmarkText: Bookmarked passage
|
||||
BookmarkType: annotation
|
||||
BookmarkTitle: Chapter 3
|
||||
|
||||
docs: |-
|
||||
## Sync Single Bookmark
|
||||
|
||||
Synchronizes an individual bookmark/highlight from Kobo device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/bookmark
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Headers:**
|
||||
- `Authorization`: Bearer {{kobo_device_token}}
|
||||
- `x-kobo-device`: Device information JSON
|
||||
|
||||
**Request Body:**
|
||||
- `ContentId` (string): Book UUID
|
||||
- `BookmarkText` (string): Highlighted text or bookmark description
|
||||
- `BookmarkType` (string): Type of bookmark
|
||||
- `annotation`: Highlighted text passage
|
||||
- `note`: Personal note
|
||||
- `bookmark`: Location marker
|
||||
- `BookmarkTitle` (string): Reference title (e.g., chapter name)
|
||||
- `ChapterID` (string, optional): Chapter identifier
|
||||
- `DateCreated` (string, optional): ISO 8601 timestamp
|
||||
- `highlight_color` (string, optional): Color name (yellow, green, blue, pink, orange)
|
||||
|
||||
**Response:**
|
||||
- `id` (string): Server bookmark ID
|
||||
- `ContentId` (string): Associated book UUID
|
||||
- `status` (string): `created`, `updated`, `skipped` (duplicate)
|
||||
- `timestamp` (string): Server timestamp
|
||||
- `url` (string): API URL to retrieve bookmark
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Bookmark created
|
||||
- 200: Bookmark updated (duplicate found)
|
||||
- 409: Duplicate bookmark (unchanged)
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid bookmark data
|
||||
|
||||
**Single Bookmark Sync vs Batch:**
|
||||
- **Single bookmark endpoint:** Real-time, immediate sync
|
||||
- **Batch markup endpoint:** Deferred, periodic sync
|
||||
- Use single when user explicitly creates highlight
|
||||
- Use batch for periodic background sync
|
||||
|
||||
**Kobo Trigger:**
|
||||
- User highlights text → immediate single sync
|
||||
- User adds note → immediate single sync
|
||||
- Device goes online → batch sync of all changes
|
||||
|
||||
**Duplicate Detection:**
|
||||
- Same ContentId + similar BookmarkText + same location
|
||||
- Updates existing if text modified
|
||||
- Skips if identical bookmark exists
|
||||
- Preserves creation date of original
|
||||
|
||||
**Use Cases:**
|
||||
- Real-time highlight sync
|
||||
- Instant note backup
|
||||
- Immediate annotation sharing
|
||||
- Quick single annotation update
|
||||
- Testing annotation sync
|
||||
|
||||
**Notes:**
|
||||
- Much faster than full markup sync
|
||||
- Lower bandwidth usage
|
||||
- Ideal for intermittent connectivity
|
||||
- Can be called multiple times safely
|
||||
@@ -0,0 +1,106 @@
|
||||
info:
|
||||
name: Sync with Annotations
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/kobo/markup'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: x-kobo-device
|
||||
value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Libra"}'
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
ReadingSync:
|
||||
- ContentId: book-uuid
|
||||
PercentRead: 55.0
|
||||
EntitlementId: entitlement-id
|
||||
RemainingTimeMinutes: 120
|
||||
FirstReadTime: '2026-01-25T10:00:00Z'
|
||||
LastModified: '2026-01-30T20:00:00Z'
|
||||
BookmarkSync:
|
||||
- ContentId: book-uuid
|
||||
BookmarkText: Important quote
|
||||
BookmarkType: annotation
|
||||
BookmarkTitle: Chapter 4 - The Truth
|
||||
- ContentId: book-uuid
|
||||
BookmarkText: Another quote
|
||||
BookmarkType: annotation
|
||||
BookmarkTitle: Chapter 5
|
||||
- ContentId: book-uuid
|
||||
BookmarkText: Note to myself
|
||||
BookmarkType: note
|
||||
BookmarkTitle: Personal note
|
||||
|
||||
docs: |-
|
||||
## Sync with Multiple Annotations
|
||||
|
||||
Synchronizes reading progress with multiple highlights and notes.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/kobo/markup
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Headers:**
|
||||
- `Authorization`: Bearer {{kobo_device_token}}
|
||||
- `x-kobo-device`: Device info (Model: "Kobo Libra")
|
||||
|
||||
**Request Body:**
|
||||
- `ReadingSync` (array): Single book progress
|
||||
- `BookmarkSync` (array): Multiple annotations
|
||||
- Can include highlights (annotation type)
|
||||
- Can include notes (note type)
|
||||
- Each has: ContentId, BookmarkText, BookmarkType, BookmarkTitle
|
||||
|
||||
**Response:**
|
||||
- `progress_synced` (boolean): Progress update status
|
||||
- `annotations_synced` (integer): Number of annotations synced
|
||||
- `highlights_count` (integer): Highlights synced
|
||||
- `notes_count` (integer): Notes synced
|
||||
- `conflicts` (array): Any annotation conflicts resolved
|
||||
- `timestamp` (string): Sync completion time
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Successful sync
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid annotation data
|
||||
|
||||
**Kobo Annotation Types:**
|
||||
- **Highlights:** Selected text passages
|
||||
- 5 preset colors available
|
||||
- Can have chapter titles
|
||||
- Exportable to PDF/Mobile
|
||||
- **Notes:** Personal annotations
|
||||
- Free-form text
|
||||
- Can be attached to highlights
|
||||
- Separate from highlights
|
||||
- **Bookmarks:** Location markers
|
||||
- Chapter positions
|
||||
- Quick navigation
|
||||
|
||||
**Sync Behavior:**
|
||||
- Duplicates detected by content matching
|
||||
- Most recent edit wins conflicts
|
||||
- Annotations linked to book content
|
||||
- Chapter references preserved
|
||||
- Order maintained from device
|
||||
|
||||
**Kobo Notebook Export:**
|
||||
- All annotations appear in Kobo "Notebook"
|
||||
- Can be exported to PDF
|
||||
- Can be exported to Mobile (text)
|
||||
- Organized by book
|
||||
- Shows highlight context
|
||||
|
||||
**Use Cases:**
|
||||
- Study and research
|
||||
- Book club discussion prep
|
||||
- Content review
|
||||
- Sharing insights
|
||||
- Personal learning archive
|
||||
@@ -0,0 +1,45 @@
|
||||
info:
|
||||
name: Kobo Bookmark Sync
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/kobo/bookmark'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"BookmarkSync\": [\n {\n \"BookmarkId\": \"bookmark_2\"\
|
||||
,\n \"ContentId\": \"kobo_xyz789\",\n \"BookmarkText\": \"Important\
|
||||
\ note\",\n \"BookmarkType\": \"bookmark\",\n \"DateCreated\"\
|
||||
: \"2026-01-31T12:00:00Z\""
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{device_token
|
||||
|
||||
docs: |-
|
||||
## Kobo Bookmark Sync
|
||||
|
||||
Synchronizes bookmarks from a Kobo device to the Bookhoard server.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/kobo/bookmark
|
||||
|
||||
**Authentication:** Bearer token (device token)
|
||||
|
||||
**Request Body:**
|
||||
- `BookmarkSync` (array): Array of bookmark objects
|
||||
- `BookmarkId` (string): Unique bookmark ID
|
||||
- `ContentId` (string): Book/content ID
|
||||
- `BookmarkText` (string): Bookmark text or note
|
||||
- `BookmarkType` (string): Type (bookmark, highlight, note)
|
||||
- `DateCreated` (string): ISO 8601 timestamp
|
||||
|
||||
**Response:**
|
||||
- `Status` (string): Sync status (Success, Partial)
|
||||
- `BookmarksSynced` (number): Number of bookmarks synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,19 @@
|
||||
info:
|
||||
name: Kobo Initialization - URL Path Token
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/v1/initialization'
|
||||
auth: none
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Kobo Initialization - URL Path Token
|
||||
|
||||
Returns initialization data for Kobo device using token in URL path.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /sync/kobo/{kobo_device_token
|
||||
@@ -0,0 +1,19 @@
|
||||
info:
|
||||
name: Get Library - URL Path Token
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/library'
|
||||
auth: none
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Kobo Library - URL Path Token
|
||||
|
||||
Retrieves library metadata for Kobo device using token in URL path.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /sync/kobo/{kobo_device_token
|
||||
@@ -0,0 +1,39 @@
|
||||
info:
|
||||
name: Get Unlinked Books - User View
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/unlinked-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{user_token
|
||||
|
||||
docs: |-
|
||||
## Get Unlinked Books - User View
|
||||
|
||||
Retrieves all unlinked books for the authenticated user that need manual linking.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/unlinked-books
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Response:**
|
||||
- `unlinked` (array): Array of unlinked book objects
|
||||
- `id` (string): Unlinked book UUID
|
||||
- `title` (string): Book title
|
||||
- `author` (string): Book author
|
||||
- `device_id` (string): Source device ID
|
||||
- `device_name` (string): Source device name
|
||||
- `detected_at` (string): Detection timestamp
|
||||
- `total` (number): Total count of unlinked books
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,34 @@
|
||||
info:
|
||||
name: Kobo Initialization
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/v1/kobo/initialization'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{device_token
|
||||
|
||||
docs: |-
|
||||
## Kobo Initialization
|
||||
|
||||
Initializes Kobo device sync, returning device resources and account information.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/v1/kobo/initialization
|
||||
|
||||
**Authentication:** Bearer token (device token)
|
||||
|
||||
**Response:**
|
||||
- `ContentId` (string): Device content ID
|
||||
- `Categories` (array): Available categories/collections
|
||||
- `BookhoardUUID` (string): Bookhoard instance UUID
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,43 @@
|
||||
info:
|
||||
name: Link Unlinked Book - Manual Resolution
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/link-book'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"unlinked_book_id\": \"{{unlinked_book_id"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{user_token
|
||||
|
||||
docs: |-
|
||||
## Link Unlinked Book - Manual Resolution
|
||||
|
||||
Manually links an unlinked book to a media item in the library.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/link-book
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `unlinked_book_id` (string): Unlinked book UUID
|
||||
- `media_item_id` (string): Media item UUID to link to
|
||||
- `confidence_score` (number): Match confidence (0-1, 1.0 for manual)
|
||||
|
||||
**Response:**
|
||||
- `status` (string): Link status (linked)
|
||||
- `unlinked_book_id` (string): Unlinked book UUID
|
||||
- `media_item_id` (string): Media item UUID
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success - book linked
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Book or media item not found
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,52 @@
|
||||
info:
|
||||
name: Kobo Markup Sync
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/kobo/markup'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"ReadingSync\": [\n {\n \"ContentId\": \"kobo_abc123def456\"\
|
||||
,\n \"PercentRead\": 60.0,\n \"RemainingTimeMin\": 120,\n \
|
||||
\ \"ReadingEvent\": \"BookRead\",\n \"LastModified\": \"2026-01-31T12:00:00Z\""
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{device_token
|
||||
|
||||
docs: |-
|
||||
## Kobo Markup Sync
|
||||
|
||||
Synchronizes reading progress and markup (highlights, bookmarks) from a Kobo device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/kobo/markup
|
||||
|
||||
**Authentication:** Bearer token (device token)
|
||||
|
||||
**Request Body:**
|
||||
- `ReadingSync` (array, optional): Reading progress data
|
||||
- `ContentId` (string): Book/content ID
|
||||
- `PercentRead` (number): Percentage read (0-100)
|
||||
- `RemainingTimeMin` (number): Remaining time in minutes
|
||||
- `ReadingEvent` (string): Event type (BookRead, etc.)
|
||||
- `LastModified` (string): ISO 8601 timestamp
|
||||
- `BookmarkSync` (array, optional): Bookmark/highlight data
|
||||
- `BookmarkId` (string): Unique bookmark ID
|
||||
- `ContentId` (string): Book/content ID
|
||||
- `BookmarkText` (string): Highlighted/bookmarked text
|
||||
- `BookmarkType` (string): Type (annotation, bookmark)
|
||||
- `DateCreated` (string): ISO 8601 timestamp
|
||||
- `Metadata` (boolean): Whether to include metadata
|
||||
|
||||
**Response:**
|
||||
- `Status` (string): Sync status (Success, Partial)
|
||||
- `MarkupsSynced` (number): Number of markups synced
|
||||
- `BookmarksSynced` (number): Number of bookmarks synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,25 @@
|
||||
info:
|
||||
name: Sync Bookmark - URL Path Token
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/bookmark'
|
||||
auth: none
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"ContentId\": \"book-uuid\",\n \"BookmarkText\": \"Highlighted\
|
||||
\ text\",\n \"BookmarkType\": \"annotation\",\n \"BookmarkTitle\": \"\
|
||||
Chapter 3\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Sync Bookmark - URL Path Token
|
||||
|
||||
Synchronizes bookmarks and annotations from Kobo device using token in URL path.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /sync/kobo/{kobo_device_token
|
||||
@@ -0,0 +1,26 @@
|
||||
info:
|
||||
name: Sync Markup - URL Path Token
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/markup'
|
||||
auth: none
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"ReadingSync\": [\n {\n \"ContentId\": \"book-uuid\"\
|
||||
,\n \"PercentRead\": 45.6,\n \"EntitlementId\": \"entitlement-id\"\
|
||||
,\n \"RemainingTimeMinutes\": 120,\n \"FirstReadTime\": \"2026-01-25T10:00:00Z\"\
|
||||
,\n \"LastModified\": \"2026-01-30T20:00:00Z\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Sync Reading Progress - URL Path Token
|
||||
|
||||
Synchronizes reading progress from Kobo device using token in URL path.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /sync/kobo/{kobo_device_token
|
||||
@@ -0,0 +1,92 @@
|
||||
info:
|
||||
name: Get Book Metadata
|
||||
type: http
|
||||
seq: 8
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/koreader/metadata/{{book_uuid}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get KOReader Book Metadata
|
||||
|
||||
Retrieves metadata for a specific book from the server.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/koreader/metadata/:book_uuid
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Path Parameters:**
|
||||
- `book_uuid` (string): SHA-256 based book identifier
|
||||
|
||||
**Response:**
|
||||
- `uuid` (string): Book UUID (SHA-256)
|
||||
- `title` (string): Book title
|
||||
- `authors` (array): Author names
|
||||
- `series` (string, optional): Series name
|
||||
- `series_index` (number, optional): Position in series
|
||||
- `publisher` (string, optional): Publisher name
|
||||
- `publication_date` (string, optional): Release date
|
||||
- `language` (string, optional): ISO 639-1 language code
|
||||
- `description` (string, optional): Book description
|
||||
- `cover_url` (string, optional): Cover image URL
|
||||
- `cover_thumbnail_url` (string, optional): Thumbnail URL
|
||||
- `identifiers` (object): Various identifiers
|
||||
- `isbn` (string, optional): ISBN-13
|
||||
- `asin` (string, optional): Amazon ASIN
|
||||
- `goodreads` (string, optional): Goodreads ID
|
||||
- `google_books` (string, optional): Google Books ID
|
||||
- `metadata_sources` (array): Sources metadata was pulled from
|
||||
- `last_synced` (string): Last metadata sync timestamp
|
||||
- `file_metadata` (object):
|
||||
- `file_size` (integer): File size in bytes
|
||||
- `format` (string): File format (epub, pdf, mobi, etc.)
|
||||
- `pages` (integer, optional): Page count
|
||||
- `word_count` (integer, optional): Estimated words
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Book not found
|
||||
|
||||
**Metadata Purpose:**
|
||||
- Enrich book information on device
|
||||
- Improve book organization
|
||||
- Enable better search
|
||||
- Support series sorting
|
||||
- Provide cover images
|
||||
- Link to external sources
|
||||
|
||||
**KOReader Usage:**
|
||||
- Display in book info dialog
|
||||
- Used for library sorting
|
||||
- Shown in file browser
|
||||
- Series grouping
|
||||
- Cover display
|
||||
- Search optimization
|
||||
|
||||
**SHA-256 Book ID:**
|
||||
- Primary identifier in KOReader
|
||||
- Universal across devices
|
||||
- Format-independent
|
||||
- Generated from file content
|
||||
- Survives metadata changes
|
||||
|
||||
**Metadata Sources:**
|
||||
- Google Books API
|
||||
- Open Library
|
||||
- Goodreads API
|
||||
- ISBN database lookup
|
||||
- Publisher metadata
|
||||
- User-provided metadata
|
||||
|
||||
**Use Cases:**
|
||||
- Initial book import
|
||||
- Metadata refresh
|
||||
- Cover image download
|
||||
- Series organization
|
||||
- Duplicate detection
|
||||
- Library management
|
||||
@@ -0,0 +1,34 @@
|
||||
info:
|
||||
name: KOReader Get Library
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/koreader/library'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Get Library
|
||||
|
||||
Retrieves the user's library for KOReader sync operations.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/koreader/library
|
||||
|
||||
**Authentication:** Bearer token (device token)
|
||||
|
||||
**Response:**
|
||||
- `library_sync` (object): Library sync data
|
||||
- `total_books` (number): Total number of books
|
||||
- `books` (array): Array of book objects
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,103 @@
|
||||
info:
|
||||
name: Get User Library for KOReader
|
||||
type: http
|
||||
seq: 9
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/koreader/library'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get KOReader User Library
|
||||
|
||||
Retrieves the user's book library for KOReader device sync.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/sync/koreader/library
|
||||
|
||||
**Authentication:** Bearer token (koreader_device_token)
|
||||
|
||||
**Query Parameters:**
|
||||
None (returns entire library)
|
||||
|
||||
**Response:**
|
||||
- `books` (array): Library items
|
||||
- `uuid` (string): SHA-256 based book identifier
|
||||
- `title` (string): Book title
|
||||
- `authors` (array): Author names
|
||||
- `series` (string, optional): Series name
|
||||
- `series_index` (number, optional): Series position
|
||||
- `publisher` (string, optional): Publisher
|
||||
- `publication_date` (string, optional): Release date
|
||||
- `language` (string, optional): Language code
|
||||
- `description` (string, optional): Description
|
||||
- `cover_url` (string, optional): Cover image URL
|
||||
- `cover_thumbnail_url` (string, optional): Thumbnail URL
|
||||
- `file_metadata` (object):
|
||||
- `format` (string): File format
|
||||
- `file_size` (integer): Size in bytes
|
||||
- `pages` (integer, optional): Page count
|
||||
- `progress` (object, optional): Reading progress
|
||||
- `percentage` (number): Progress 0-100
|
||||
- `last_read` (string): Last read timestamp
|
||||
- `epubcfi` (string): Current position
|
||||
- `annotations_count` (object, optional): Annotation stats
|
||||
- `highlights` (integer): Highlight count
|
||||
- `notes` (integer): Note count
|
||||
- `bookmarks` (integer): Bookmark count
|
||||
- `library_info` (object):
|
||||
- `total_books` (integer): Total book count
|
||||
- `last_sync` (string): Last library sync timestamp
|
||||
- `has_updates` (boolean): Updates available
|
||||
- `user_info` (object):
|
||||
- `user_id` (string): User identifier
|
||||
- `email` (string): Email (masked)
|
||||
- `libraries` (array): Available library IDs
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Device not approved
|
||||
|
||||
**Library Purpose for KOReader:**
|
||||
- Discover books available for download
|
||||
- Browse catalog on device
|
||||
- Sync reading progress across books
|
||||
- Download covers/metadata
|
||||
- Series-based organization
|
||||
- Cloud library access
|
||||
|
||||
**KOReader Device Features:**
|
||||
- **OPDS catalog**: Native OPDS client
|
||||
- **File browser**: See server books
|
||||
- **Cloud download**: Download books on-demand
|
||||
- **Metadata sync**: Automatic metadata fetching
|
||||
- **Cover images**: Display in library view
|
||||
- **Progress sync**: See progress across all books
|
||||
- **Search**: Search library by title/author
|
||||
|
||||
**KOReader-Specific Features:**
|
||||
- SHA-256 based book IDs
|
||||
- Multi-format support (EPUB, FB2, PDF, DJVU, MOBI, etc.)
|
||||
- Series sorting and grouping
|
||||
- Language filtering
|
||||
- Cover image caching
|
||||
- Metadata for file browser enhancement
|
||||
- Integration with KOReader's OPDS client
|
||||
|
||||
**Performance:**
|
||||
- Typical response: 100-500KB for 100 books
|
||||
- Processing time: 300ms-1s
|
||||
- Cache duration: 5 minutes
|
||||
- Pagination support for libraries >500 books
|
||||
|
||||
**Use Cases:**
|
||||
- Initial device setup
|
||||
- Library browsing on device
|
||||
- Book download
|
||||
- Metadata refresh
|
||||
- Cover image sync
|
||||
- Progress overview
|
||||
- Series-based reading
|
||||
@@ -0,0 +1,7 @@
|
||||
info:
|
||||
name: Bookhoard KOReader Sync API
|
||||
type: collection
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '"http://localhost:8765/api"'
|
||||
@@ -0,0 +1,123 @@
|
||||
info:
|
||||
name: Checkpoint Sync
|
||||
type: http
|
||||
seq: 11
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
sync_mode: checkpoint
|
||||
checkpoint_id: checkpoint-uuid
|
||||
since_timestamp: '2026-01-30T19:00:00Z'
|
||||
books:
|
||||
- uuid: book-uuid-1
|
||||
percentage: 0.45
|
||||
chapter: 3
|
||||
- uuid: book-uuid-2
|
||||
percentage: 0.75
|
||||
chapter: 8
|
||||
|
||||
docs: |-
|
||||
## Checkpoint Sync
|
||||
|
||||
Incremental sync using checkpoint-based change tracking.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `sync_mode` (string): Must be `checkpoint`
|
||||
- `checkpoint_id` (string): Unique checkpoint identifier
|
||||
- `since_timestamp` (string): ISO 8601 timestamp for incremental sync
|
||||
- `books` (array): Book progress items
|
||||
- `uuid` (string): Book UUID
|
||||
- `percentage` (number): Progress 0.0-1.0
|
||||
- `chapter` (integer): Current chapter
|
||||
- `epubcfi` (string, optional): Current position
|
||||
- `modified_since` (boolean, optional): Whether modified since checkpoint
|
||||
|
||||
**Response:**
|
||||
- `checkpoint_id` (string): Server checkpoint ID
|
||||
- `checkpoint_timestamp` (string): Checkpoint creation time
|
||||
- `processed` (integer): Books processed
|
||||
- `changes_only` (boolean): Whether only changed items synced
|
||||
- `next_checkpoint_id` (string): ID for next checkpoint sync
|
||||
- `results` (array): Per-book results
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Checkpoint sync completed
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid checkpoint or timestamp
|
||||
|
||||
**Checkpoint Sync Benefits:**
|
||||
- **Incremental**: Only sync changed items
|
||||
- **Efficient**: Smaller payloads
|
||||
- **Fast**: Reduced processing time
|
||||
- **Reliable**: Checkpoint-based tracking
|
||||
- **Resumable**: Can continue from last checkpoint
|
||||
|
||||
**Checkpoint Mechanism:**
|
||||
- Server tracks changes since checkpoint
|
||||
- Client provides checkpoint ID or timestamp
|
||||
- Only modified books returned/processed
|
||||
- Checkpoint ID advances on each sync
|
||||
- Supports large libraries efficiently
|
||||
|
||||
**Use Cases:**
|
||||
- Large libraries (100+ books)
|
||||
- Intermittent connectivity
|
||||
- Bandwidth optimization
|
||||
- Battery conservation
|
||||
- Background sync
|
||||
- Periodic sync (every 5-15 minutes)
|
||||
|
||||
**Checkpoint Lifecycle:**
|
||||
1. Initial sync: No checkpoint (full sync)
|
||||
2. Server returns checkpoint_id
|
||||
3. Next sync: Client sends checkpoint_id
|
||||
4. Server processes only changes
|
||||
5. New checkpoint_id returned
|
||||
6. Repeat from step 3
|
||||
|
||||
**Sync Optimization:**
|
||||
- Only books with progress changes
|
||||
- Skips unmodified books
|
||||
- Delta transfer
|
||||
- Compression for large payloads
|
||||
- Batch processing
|
||||
|
||||
**Failure Handling:**
|
||||
- Checkpoint ID preserved on failure
|
||||
- Retry with same checkpoint
|
||||
- Full sync if checkpoint expired
|
||||
- Checkpoint validity: 24 hours
|
||||
- Auto-fallback to full sync
|
||||
|
||||
**Performance:**
|
||||
- Small changes (1-10 books): 100-300ms
|
||||
- Medium changes (10-50 books): 300ms-1s
|
||||
- Large changes (50-100 books): 1-3s
|
||||
- Typical: 5-10x faster than full sync
|
||||
|
||||
**When to Use:**
|
||||
- Default sync mode for most users
|
||||
- Periodic background sync
|
||||
- Large library management
|
||||
- Mobile/network-constrained environments
|
||||
- Battery-powered devices
|
||||
|
||||
**Configuration:**
|
||||
- Checkpoint expiration: 24 hours
|
||||
- Max history: 100 checkpoints
|
||||
- Auto-cleanup of old checkpoints
|
||||
- Configurable sync interval
|
||||
@@ -0,0 +1,105 @@
|
||||
info:
|
||||
name: Immediate Sync - Page Turn
|
||||
type: http
|
||||
seq: 10
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
sync_mode: immediate
|
||||
books:
|
||||
- uuid: book-uuid
|
||||
percentage: 0.45678
|
||||
chapter: 3
|
||||
timestamp: '2026-01-30T20:00:00Z'
|
||||
|
||||
docs: |-
|
||||
## Immediate Sync - Page Turn
|
||||
|
||||
Real-time progress sync triggered immediately on page turn.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `sync_mode` (string): Must be `immediate`
|
||||
- `books` (array): Current book progress
|
||||
- `uuid` (string): Book UUID
|
||||
- `percentage` (number): Precise progress (0.45678 = 45.678%)
|
||||
- `chapter` (integer): Current chapter
|
||||
- `timestamp` (string): ISO 8601 timestamp
|
||||
- `epubcfi` (string, optional): Current position
|
||||
- `page` (integer, optional): Current page
|
||||
|
||||
**Response:**
|
||||
- `synced` (boolean): Immediate sync status
|
||||
- `timestamp` (string): Server timestamp
|
||||
- `next_sync_suggested` (string): Suggested next sync time
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Sync queued
|
||||
- 202: Accepted for processing
|
||||
- 401: Unauthorized
|
||||
- 429: Too many immediate sync requests (rate limited)
|
||||
|
||||
**Immediate Sync Mode:**
|
||||
- **Purpose**: Real-time progress updates
|
||||
- **Trigger**: Every page turn (configurable)
|
||||
- **Priority**: High priority processing
|
||||
- **Latency**: <100ms typical
|
||||
- **Best effort**: May be queued under load
|
||||
|
||||
**Rate Limiting:**
|
||||
- Max 60 requests per minute per device
|
||||
- Throttled after limit reached
|
||||
- Suggests switching to periodic sync
|
||||
- Prevents server overload
|
||||
|
||||
**Use Cases:**
|
||||
- Real-time multi-device reading
|
||||
- Live progress sharing
|
||||
- Instant position backup
|
||||
- Critical reading points
|
||||
- Test/profiling mode
|
||||
|
||||
**Performance:**
|
||||
- Ultra-fast sync
|
||||
- Minimal payload
|
||||
- Optimized for speed
|
||||
- Async processing
|
||||
- No confirmation wait
|
||||
|
||||
**Battery Considerations:**
|
||||
- More frequent network use
|
||||
- Higher battery consumption
|
||||
- WiFi recommended
|
||||
- Can reduce sync frequency in settings
|
||||
|
||||
**Configuration:**
|
||||
- Can enable/disable per device
|
||||
- Adjustable frequency (every page, every N pages)
|
||||
- Automatic fallback to periodic sync on error
|
||||
- Respects device power-save mode
|
||||
|
||||
**When to Use:**
|
||||
- Critical reading sessions
|
||||
- Multi-device concurrent reading
|
||||
- Research and study
|
||||
- Testing sync functionality
|
||||
- When power source available
|
||||
|
||||
**When NOT to Use:**
|
||||
- Battery conservation needed
|
||||
- Unstable network
|
||||
- Extended reading sessions
|
||||
- Background sync preferred
|
||||
@@ -0,0 +1,44 @@
|
||||
info:
|
||||
name: KOReader Sync Annotations - Per-Book SHA-256
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_uuid\": \"{{book_uuid"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{koreader_device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Sync Annotations - Per-Book SHA-256
|
||||
|
||||
Synchronizes annotations (highlights) from KOReader with per-annotation SHA-256 hashes for multi-book sync.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/koreader/sync/bookmarks
|
||||
|
||||
**Authentication:** Bearer token (KOReader device token)
|
||||
|
||||
**Request Body:**
|
||||
- `book_uuid` (string): Primary book UUID
|
||||
- `highlights` (array): Array of highlight objects
|
||||
- `text` (string): Highlighted text
|
||||
- `pos0`, `pos1` (string): EPUB CFI positions
|
||||
- `color` (string): Highlight color (hex)
|
||||
- `page` (number): Page number
|
||||
- `book_sha256` (string): SHA-256 hash for this specific book
|
||||
|
||||
**Response:**
|
||||
- `highlights_synced` (number): Number of highlights synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** Each highlight can include its own book_sha256, allowing annotations from multiple books in a single request.
|
||||
@@ -0,0 +1,40 @@
|
||||
info:
|
||||
name: KOReader Sync Bookmarks - SHA-256
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_sha256\": \"{{book_sha256"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{koreader_device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Sync Bookmarks - SHA-256
|
||||
|
||||
Synchronizes bookmarks, notes, and highlights from KOReader using SHA-256 hash for book identification.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/koreader/sync/bookmarks
|
||||
|
||||
**Authentication:** Bearer token (KOReader device token)
|
||||
|
||||
**Request Body:**
|
||||
- `book_sha256` (string): SHA-256 hash of book file
|
||||
- `bookmarks` (array): Array of bookmarks
|
||||
- `notes` (array): Array of notes
|
||||
- `highlights` (array): Array of highlights
|
||||
|
||||
**Response:**
|
||||
- `sync_status` (string): Sync status
|
||||
- `total_synced` (number): Total items synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,105 @@
|
||||
info:
|
||||
name: Sync Bookmarks
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/bookmarks'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid
|
||||
bookmarks:
|
||||
- chapter: 3
|
||||
datetime: '2026-01-30T19:55:00Z'
|
||||
notes: Marked this chapter as important
|
||||
pos0: 'epubcfi(/6/4/2:15)'
|
||||
pos1: 'epubcfi(/6/4/2:20)'
|
||||
page: 45
|
||||
text: Important passage
|
||||
type: bookmark
|
||||
|
||||
docs: |-
|
||||
## Sync KOReader Bookmarks
|
||||
|
||||
Synchronizes bookmarks separately from progress for KOReader.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/bookmarks
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Books with bookmarks
|
||||
- `uuid` (string): Book UUID
|
||||
- `bookmarks` (array): Bookmark items
|
||||
- `chapter` (integer): Chapter number
|
||||
- `datetime` (string): ISO 8601 timestamp
|
||||
- `notes` (string): Bookmark description
|
||||
- `pos0` (string): EPUB CFI start position
|
||||
- `pos1` (string): EPUB CFI end position
|
||||
- `page` (integer): Page number
|
||||
- `text` (string): Displayed text
|
||||
- `type` (string): `bookmark`, `highlight`, or `note`
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Number of bookmarks synced
|
||||
- `duplicates_skipped` (integer): Duplicate bookmarks skipped
|
||||
- `results` (array): Per-bookmark results
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid data
|
||||
|
||||
**Dedicated Bookmark Endpoint:**
|
||||
- **Purpose**: Sync bookmarks independently
|
||||
- **Use case**: More frequent bookmark updates
|
||||
- **Advantage**: Separate from progress sync
|
||||
- **Efficiency**: Smaller payloads
|
||||
|
||||
**KOReader Bookmark Features:**
|
||||
- Chapter-based organization
|
||||
- Quick navigation markers
|
||||
- Hierarchical bookmarks (via plugins)
|
||||
- Custom bookmark titles
|
||||
- Date/time tracking
|
||||
- EPUB CFI precision
|
||||
|
||||
**Bookmark Types in KOReader:**
|
||||
- **Location bookmarks**: Quick navigation points
|
||||
- **Chapter marks**: Auto-generated chapter markers
|
||||
- **Progress bookmarks**: Last read positions
|
||||
- **Custom bookmarks**: User-created markers
|
||||
- **Search bookmarks**: Saved search results
|
||||
|
||||
**Sync Behavior:**
|
||||
- Duplicate detection by position + text
|
||||
- Most recent wins on conflicts
|
||||
- Chapter order preserved
|
||||
- Auto-generated vs manual bookmarks differentiated
|
||||
- Merge with existing bookmarks
|
||||
|
||||
**KOReader Device Integration:**
|
||||
- Created via "Add bookmark" menu
|
||||
- Shown in "Bookmarks" panel
|
||||
- Quick access via "Go to bookmark"
|
||||
- Exportable to JSON
|
||||
- Can be edited/deleted
|
||||
|
||||
**Use Cases:**
|
||||
- Quick navigation aids
|
||||
- Chapter markers
|
||||
- Important passages
|
||||
- Reading progress points
|
||||
- Study session markers
|
||||
@@ -0,0 +1,110 @@
|
||||
info:
|
||||
name: Sync Highlights
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/highlights'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid
|
||||
highlights:
|
||||
- datetime: '2026-01-30T19:50:00Z'
|
||||
text: Important quote from book
|
||||
chapter: 4
|
||||
pos0: 'epubcfi(/6/4/2:20)'
|
||||
pos1: 'epubcfi(/6/4/2:30)'
|
||||
page_start: 78
|
||||
page_end: 79
|
||||
|
||||
docs: |-
|
||||
## Sync KOReader Highlights
|
||||
|
||||
Synchronizes text highlights separately from other annotations.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/highlights
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Books with highlights
|
||||
- `uuid` (string): Book UUID
|
||||
- `highlights` (array): Highlight items
|
||||
- `datetime` (string): Creation timestamp
|
||||
- `text` (string): Highlighted text content
|
||||
- `chapter` (integer): Chapter number
|
||||
- `pos0` (string): EPUB CFI start position
|
||||
- `pos1` (string): EPUB CFI end position
|
||||
- `page_start` (integer): Start page
|
||||
- `page_end` (integer): End page
|
||||
- `color` (string, optional): Color name or hex
|
||||
- `note` (string, optional): Attached note
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Highlights synced
|
||||
- `duplicates_skipped` (integer): Duplicates found
|
||||
- `with_notes` (integer): Highlights that have notes attached
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**KOReader Highlight Features:**
|
||||
- Precise text selection (EPUB CFI)
|
||||
- Custom color support (via plugins)
|
||||
- Multi-page highlights
|
||||
- Chapter references
|
||||
- Timestamps for sorting
|
||||
- Attached notes support
|
||||
- Full text preservation
|
||||
|
||||
**Highlight Colors (via plugins):**
|
||||
- Yellow (default): General highlighting
|
||||
- Green: Important concepts
|
||||
- Blue: Key information
|
||||
- Red/pink: Critical content
|
||||
- Orange: Interesting quotes
|
||||
- Custom RGB colors available
|
||||
|
||||
**EPUB CFI Advantages:**
|
||||
- Precise start/end positions
|
||||
- Works across font size changes
|
||||
- Survives text reflow
|
||||
- Device-independent
|
||||
- Standardized format
|
||||
|
||||
**Dedicated Highlight Endpoint:**
|
||||
- **Separate from progress**: Sync highlights independently
|
||||
- **Smaller payload**: Just highlights, no progress
|
||||
- **More frequent**: Can sync highlights immediately
|
||||
- **Focused**: Single-purpose endpoint
|
||||
|
||||
**Sync Behavior:**
|
||||
- Exact text matching for duplicates
|
||||
- Position-based conflict resolution
|
||||
- Color preservation across devices
|
||||
- Note attachments preserved
|
||||
- Order maintained by position
|
||||
|
||||
**KOReader Device Features:**
|
||||
- Created via long-press or selection
|
||||
- Color picker available
|
||||
- Can add notes immediately
|
||||
- Shows in "Highlights" panel
|
||||
- Exportable to Evernote, etc.
|
||||
- Searchable by content
|
||||
|
||||
**Use Cases:**
|
||||
- Study and research
|
||||
- Content curation
|
||||
- Quote collection
|
||||
- Academic work
|
||||
- Sharing insights
|
||||
@@ -0,0 +1,108 @@
|
||||
info:
|
||||
name: Sync Notes
|
||||
type: http
|
||||
seq: 7
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/notes'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid
|
||||
notes:
|
||||
- datetime: '2026-01-30T19:52:00Z'
|
||||
text: My personal note about this chapter
|
||||
chapter: 4
|
||||
|
||||
docs: |-
|
||||
## Sync KOReader Notes
|
||||
|
||||
Synchronizes user notes separately from highlights and bookmarks.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/notes
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Books with notes
|
||||
- `uuid` (string): Book UUID
|
||||
- `notes` (array): Note items
|
||||
- `datetime` (string): Creation/modification timestamp
|
||||
- `text` (string): Note content
|
||||
- `chapter` (integer): Chapter number
|
||||
- `pos0` (string, optional): Related EPUB CFI position
|
||||
- `page` (integer, optional): Page number
|
||||
- `highlighted_text` (string, optional): Related highlight
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Notes synced
|
||||
- `duplicates_skipped` (integer): Duplicate notes found
|
||||
- `attached_to_highlights` (integer): Notes linked to highlights
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**KOReader Note Features:**
|
||||
- Free-form text notes
|
||||
- Can be standalone or attached to highlights
|
||||
- Chapter-based organization
|
||||
- Timestamped for sorting
|
||||
- Markdown support (some versions)
|
||||
- Longer form content
|
||||
- No character limit
|
||||
|
||||
**Note Types:**
|
||||
- **Standalone notes**: Independent notes about chapter/section
|
||||
- **Attached notes**: Notes attached to specific highlights
|
||||
- **Chapter notes**: Notes about entire chapter
|
||||
- **Book notes**: General notes about the book
|
||||
|
||||
**Dedicated Notes Endpoint:**
|
||||
- **Separate sync**: Notes sync independently
|
||||
- **Flexible**: Not tied to highlights
|
||||
- **Efficient**: Smaller, focused payload
|
||||
- **Immediate**: Can sync right after note creation
|
||||
|
||||
**Attached Notes:**
|
||||
- Linked to specific highlight
|
||||
- Shares highlight's position
|
||||
- Shown together with highlight
|
||||
- Deleted when highlight deleted (optional)
|
||||
- Color matches highlight
|
||||
|
||||
**Sync Behavior:**
|
||||
- Text-based duplicate detection
|
||||
- Time-based conflict resolution
|
||||
- Chapter organization preserved
|
||||
- Markdown formatting preserved
|
||||
- Attachment links maintained
|
||||
|
||||
**KOReader Device Integration:**
|
||||
- Created via "Add note" option
|
||||
- Edited in note editor
|
||||
- Shown in "Notes" panel
|
||||
- Can be organized by chapter
|
||||
- Export functionality available
|
||||
- Search support
|
||||
|
||||
**Advanced Features:**
|
||||
- **Markdown**: Bold, italic, lists (some versions)
|
||||
- **Tags**: User-defined tags (via plugins)
|
||||
- **Links**: Internal/external links
|
||||
- **Formatting**: Rich text in newer versions
|
||||
|
||||
**Use Cases:**
|
||||
- Study notes
|
||||
- Personal reflections
|
||||
- Academic annotations
|
||||
- Research insights
|
||||
- Book club discussion prep
|
||||
- Knowledge management
|
||||
@@ -0,0 +1,47 @@
|
||||
info:
|
||||
name: KOReader Sync Progress - SHA-256 Only
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/koreader/sync/progress'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"sync_mode\": \"immediate\",\n \"books\": [\n {\n \
|
||||
\ \"sha256\": \"{{book_sha256"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{koreader_device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Sync Progress - SHA-256 Only
|
||||
|
||||
Synchronizes reading progress using only SHA-256 hash for book identification (when UUID is not available).
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/koreader/sync/progress
|
||||
|
||||
**Authentication:** Bearer token (KOReader device token)
|
||||
|
||||
**Request Body:**
|
||||
- `sync_mode` (string): Sync mode (immediate, deferred)
|
||||
- `books` (array): Array of book progress objects
|
||||
- `sha256` (string): SHA-256 hash of book file
|
||||
- `file_path` (string): Path to book file
|
||||
- `percentage` (number): Progress percentage
|
||||
- `page` (number): Current page
|
||||
- `total_pages` (number): Total pages
|
||||
|
||||
**Response:**
|
||||
- `sync_status` (string): Sync status
|
||||
- `books_synced` (number): Number of books synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 202: Accepted
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** Use this when book UUID is not available, falling back to SHA-256 hash for identification.
|
||||
@@ -0,0 +1,51 @@
|
||||
info:
|
||||
name: KOReader Sync Progress - SHA-256
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/v1/koreader/sync/progress'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"sync_mode\": \"immediate\",\n \"books\": [\n {\n \
|
||||
\ \"uuid\": \"{{book_uuid"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{koreader_device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Sync Progress - SHA-256
|
||||
|
||||
Synchronizes reading progress from a KOReader device using SHA-256 book hash for identification.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/v1/koreader/sync/progress
|
||||
|
||||
**Authentication:** Bearer token (KOReader device token)
|
||||
|
||||
**Request Body:**
|
||||
- `sync_mode` (string): Sync mode (immediate, deferred)
|
||||
- `books` (array): Array of book progress objects
|
||||
- `uuid` (string): Book UUID
|
||||
- `sha256` (string): SHA-256 hash of book file for identification
|
||||
- `file_path` (string): Path to book file on device
|
||||
- `percentage` (number): Progress percentage (0-1)
|
||||
- `chapter` (number): Current chapter
|
||||
- `page` (number): Current page
|
||||
- `total_pages` (number): Total pages
|
||||
- `epubcfi` (string): EPUB location
|
||||
- `last_read` (string): ISO 8601 timestamp
|
||||
- `title` (string): Book title
|
||||
- `authors` (array): List of authors
|
||||
|
||||
**Response:**
|
||||
- `sync_status` (string): Sync status
|
||||
- `books_synced` (number): Number of books synced
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 202: Accepted - processing
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,90 @@
|
||||
info:
|
||||
name: Sync Progress - Multiple Books
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-1-uuid
|
||||
title: Book One
|
||||
authors:
|
||||
- Author One
|
||||
progress: 0.25
|
||||
percentage: 0.25
|
||||
last_read: '2026-01-30T19:00:00Z'
|
||||
chapter: 1
|
||||
epubcfi: 'epubcfi(/6/4/2:10)'
|
||||
- uuid: book-2-uuid
|
||||
title: Book Two
|
||||
authors:
|
||||
- Author Two
|
||||
progress: 0.75
|
||||
percentage: 0.75
|
||||
last_read: '2026-01-30T20:00:00Z'
|
||||
chapter: 8
|
||||
epubcfi: 'epubcfi(/6/4/2:50)'
|
||||
|
||||
docs: |-
|
||||
## Sync KOReader Progress - Multiple Books
|
||||
|
||||
Synchronizes reading progress for multiple books in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Multiple book progress items
|
||||
- Each item contains: uuid, title, authors, progress, percentage, last_read, chapter, epubcfi
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Number of books successfully synced
|
||||
- `failed` (integer): Number of books that failed
|
||||
- `results` (array): Per-book sync results
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Batch sync completed
|
||||
- 207: Multi-status (partial success)
|
||||
- 401: Unauthorized
|
||||
- 413: Payload too large
|
||||
|
||||
**Batch Sync Advantages:**
|
||||
- Efficient sync of entire library
|
||||
- Single HTTP request for multiple books
|
||||
- Faster periodic sync
|
||||
- Reduced battery usage vs individual syncs
|
||||
- Better for batch processing
|
||||
|
||||
**KOReader Batch Behavior:**
|
||||
- Triggered on device wake from sleep
|
||||
- Occurs during "Sync now" operation
|
||||
- Runs on WiFi connection
|
||||
- Limited to 100 books per request
|
||||
- Automatic retry on failed books
|
||||
|
||||
**Performance:**
|
||||
- Small batch (2-10 books): 200-500ms
|
||||
- Medium batch (10-50 books): 500ms-2s
|
||||
- Large batch (50-100 books): 2-5s
|
||||
- Timeout: 30 seconds
|
||||
|
||||
**Use Cases:**
|
||||
- Device initialization sync
|
||||
- Periodic background sync
|
||||
- Post-offline catch-up sync
|
||||
- Library-wide progress update
|
||||
- Before firmware update
|
||||
@@ -0,0 +1,92 @@
|
||||
info:
|
||||
name: Sync Progress - Single Book
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid-here
|
||||
title: Book Title
|
||||
authors:
|
||||
- Author Name
|
||||
progress: 0.45
|
||||
percentage: 0.45
|
||||
last_read: '2026-01-30T20:00:00Z'
|
||||
chapter: 3
|
||||
epubcfi: 'epubcfi(/6/4/2:15)'
|
||||
character: 15432
|
||||
|
||||
docs: |-
|
||||
## Sync KOReader Progress - Single Book
|
||||
|
||||
Synchronizes reading progress for a single book from KOReader device.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token (koreader_device_token)
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID for multi-library setups
|
||||
- `books` (array): Array with single book progress
|
||||
- `uuid` (string): Unique book identifier (often SHA-256 hash)
|
||||
- `title` (string): Book title
|
||||
- `authors` (array): List of authors
|
||||
- `progress` (number): Progress decimal (0.0 to 1.0)
|
||||
- `percentage` (number): Progress percentage (0.45 = 45%)
|
||||
- `last_read` (string): ISO 8601 timestamp of last read
|
||||
- `chapter` (integer): Current chapter number
|
||||
- `epubcfi` (string): EPUB Canonical Fragment Identifier
|
||||
- `character` (integer): Character position in book
|
||||
- `page` (integer, optional): Current page number
|
||||
|
||||
**Response:**
|
||||
- `synced` (integer): Number of books synced
|
||||
- `timestamp` (string): Server sync timestamp
|
||||
- `books` (array): Sync results
|
||||
- `uuid` (string): Book UUID
|
||||
- `status` (string): `synced`, `updated`, `skipped`
|
||||
- `server_progress` (object): Server-side progress data
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 400: Invalid request format
|
||||
|
||||
**KOReader Progress Tracking:**
|
||||
- SHA-256 based book identification (universal across devices)
|
||||
- EPUB CFI for precise location (standard format)
|
||||
- Chapter-based navigation
|
||||
- Character-level precision
|
||||
- Supports EPUB, FB2, PDF, DJVU, MOBI formats
|
||||
|
||||
**EPUB CFI Format:**
|
||||
- Standardized location format for EPUBs
|
||||
- Example: `epubcfi(/6/4/2:15)`
|
||||
- Identifies exact position even after reflow
|
||||
- Works across different devices/apps
|
||||
- Preserved after file modifications
|
||||
|
||||
**Book Identification:**
|
||||
- Primary: SHA-256 hash of book file
|
||||
- Universal: Same book = same UUID across devices
|
||||
- Format-agnostic: Works for any supported format
|
||||
- Case-sensitive: Hash must match exactly
|
||||
|
||||
**Use Cases:**
|
||||
- Real-time page turn sync
|
||||
- Progress backup
|
||||
- Cross-device continuity
|
||||
- Reading time tracking
|
||||
- Chapter completion detection
|
||||
@@ -0,0 +1,106 @@
|
||||
info:
|
||||
name: Sync Progress - With Bookmarks
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid-here
|
||||
title: Book Title
|
||||
authors:
|
||||
- Author Name
|
||||
progress: 0.45
|
||||
percentage: 0.45
|
||||
last_read: '2026-01-30T20:00:00Z'
|
||||
bookmarks:
|
||||
- chapter: 3
|
||||
datetime: '2026-01-30T19:55:00Z'
|
||||
notes: highlighted text
|
||||
pos0: 'epubcfi(/6/4/2:15)'
|
||||
pos1: 'epubcfi(/6/4/2:20)'
|
||||
page: 45
|
||||
text: highlighted text excerpt
|
||||
type: highlight
|
||||
|
||||
docs: |-
|
||||
## Sync Progress with Bookmarks
|
||||
|
||||
Synchronizes reading progress with bookmarks/highlights from KOReader.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Books with progress and bookmarks
|
||||
- `uuid`, `title`, `authors`, `progress`, etc.
|
||||
- `bookmarks` (array): Bookmark items
|
||||
- `chapter` (integer): Chapter number
|
||||
- `datetime` (string): ISO 8601 timestamp
|
||||
- `notes` (string): Note content or highlighted text
|
||||
- `pos0` (string): EPUB CFI start position
|
||||
- `pos1` (string): EPUB CFI end position
|
||||
- `page` (integer): Page number
|
||||
- `text` (string): Displayed text excerpt
|
||||
- `type` (string): `highlight`, `bookmark`, or `note`
|
||||
|
||||
**Response:**
|
||||
- `progress_synced` (integer): Progress items synced
|
||||
- `bookmarks_synced` (integer): Bookmark items synced
|
||||
- `highlights_synced` (integer): Highlight count
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**KOReader Bookmark Types:**
|
||||
- **highlight**: Selected text passages
|
||||
- **bookmark**: Location markers
|
||||
- **note**: Text annotations (can be attached to highlights)
|
||||
|
||||
**KOReader Highlight Features:**
|
||||
- Custom colors (via color extensions)
|
||||
- Multi-color support
|
||||
- Precise EPUB CFI positioning
|
||||
- Chapter-based organization
|
||||
- Text excerpts preserved
|
||||
- Date/time stamped
|
||||
- Page number tracking
|
||||
|
||||
**EPUB CFI in Bookmarks:**
|
||||
- `pos0`: Start position (highlight start)
|
||||
- `pos1`: End position (highlight end)
|
||||
- Exact text selection boundaries
|
||||
- Survives text reflow
|
||||
- Works across different font sizes
|
||||
|
||||
**Sync Behavior:**
|
||||
- Duplicate detection by text + position
|
||||
- Most recent edit wins
|
||||
- Chapter references maintained
|
||||
- Order preserved from device
|
||||
- Merges with existing server bookmarks
|
||||
|
||||
**KOReader Device Integration:**
|
||||
- Created in KOReader highlight interface
|
||||
- Shows in "Bookmarks" menu
|
||||
- Can be edited/deleted on device
|
||||
- Exportable to JSON/XML
|
||||
- Searchable by content
|
||||
|
||||
**Use Cases:**
|
||||
- Study and research
|
||||
- Content review
|
||||
- Passage tracking
|
||||
- Quick navigation
|
||||
- Cross-device bookmark access
|
||||
@@ -0,0 +1,117 @@
|
||||
info:
|
||||
name: Sync Progress - With Highlights and Notes
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
library_id: optional-library-uuid
|
||||
books:
|
||||
- uuid: book-uuid-here
|
||||
title: Book Title
|
||||
authors:
|
||||
- Author Name
|
||||
progress: 0.6
|
||||
percentage: 0.6
|
||||
last_read: '2026-01-30T20:00:00Z'
|
||||
highlights:
|
||||
- datetime: '2026-01-30T19:50:00Z'
|
||||
text: Important passage
|
||||
chapter: 4
|
||||
pos0: 'epubcfi(/6/4/2:20)'
|
||||
pos1: 'epubcfi(/6/4/2:30)'
|
||||
page_start: 78
|
||||
page_end: 79
|
||||
notes:
|
||||
- datetime: '2026-01-30T19:52:00Z'
|
||||
text: My note about this chapter
|
||||
chapter: 4
|
||||
|
||||
docs: |-
|
||||
## Sync Progress with Highlights and Notes
|
||||
|
||||
Synchronizes reading progress with separate highlights and notes arrays.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Books with progress and annotations
|
||||
- `uuid`, `title`, `authors`, `progress`, `percentage`, `last_read`
|
||||
- `highlights` (array): Text highlights
|
||||
- `datetime` (string): Creation timestamp
|
||||
- `text` (string): Highlighted text content
|
||||
- `chapter` (integer): Chapter number
|
||||
- `pos0` (string): EPUB CFI start
|
||||
- `pos1` (string): EPUB CFI end
|
||||
- `page_start` (integer): Start page
|
||||
- `page_end` (integer): End page
|
||||
- `color` (string, optional): Highlight color
|
||||
- `notes` (array): Notes
|
||||
- `datetime` (string): Creation timestamp
|
||||
- `text` (string): Note content
|
||||
- `chapter` (integer): Chapter number
|
||||
- `pos0` (string, optional): Related position
|
||||
|
||||
**Response:**
|
||||
- `progress_synced` (boolean): Progress sync status
|
||||
- `highlights_synced` (integer): Highlights synced
|
||||
- `notes_synced` (integer): Notes synced
|
||||
- `conflicts_resolved` (integer): Conflict count
|
||||
- `timestamp` (string): Sync timestamp
|
||||
|
||||
**KOReader Annotation Model:**
|
||||
- **Separate arrays**: Highlights and notes stored separately
|
||||
- **Linked**: Notes can reference highlights
|
||||
- **Rich metadata**: Timestamps, positions, page numbers
|
||||
- **Flexible**: Supports complex annotations
|
||||
|
||||
**Highlight Features:**
|
||||
- Multi-color highlighting (via plugins)
|
||||
- Precise text selection with EPUB CFI
|
||||
- Page range tracking
|
||||
- Chapter references
|
||||
- Timestamps for sorting
|
||||
- Full text preserved
|
||||
|
||||
**Note Features:**
|
||||
- Free-form text notes
|
||||
- Can be standalone or attached
|
||||
- Chapter-based organization
|
||||
- Timestamped
|
||||
- Longer form than highlights
|
||||
- Support for markdown (some versions)
|
||||
|
||||
**Color Support (via plugins):**
|
||||
- Yellow: Default highlight
|
||||
- Green: Important passages
|
||||
- Blue: Key concepts
|
||||
- Red: Critical information
|
||||
- Orange: Interesting quotes
|
||||
- Custom colors available
|
||||
|
||||
**Sync Advantages:**
|
||||
- Separation allows granular control
|
||||
- Highlights sync without notes
|
||||
- Notes sync independently
|
||||
- Better conflict resolution
|
||||
- Efficient for large annotation sets
|
||||
|
||||
**Use Cases:**
|
||||
- Academic research
|
||||
- Study groups
|
||||
- Content analysis
|
||||
- Personal knowledge management
|
||||
- Sharing insights
|
||||
@@ -0,0 +1,53 @@
|
||||
info:
|
||||
name: KOReader Sync Progress
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/koreader/progress'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"library_id\": null,\n \"books\": [\n {\n \"\
|
||||
uuid\": \"{{book_uuid"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{device_token
|
||||
|
||||
docs: |-
|
||||
## KOReader Sync Progress
|
||||
|
||||
Synchronizes reading progress from a KOReader device to the Bookhoard server.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/sync/koreader/progress
|
||||
|
||||
**Authentication:** Bearer token (device token)
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, optional): Library UUID
|
||||
- `books` (array): Array of book progress objects
|
||||
- `uuid` (string): Book UUID
|
||||
- `title` (string): Book title
|
||||
- `authors` (array): List of authors
|
||||
- `progress` (number): Progress value
|
||||
- `percentage` (number): Percentage complete (0-1)
|
||||
- `last_read` (string): ISO 8601 timestamp
|
||||
- `chapter` (number): Current chapter
|
||||
- `epubcfi` (string): EPUB Canonical Fragment Identifier
|
||||
- `page` (number): Current page
|
||||
- `total_pages` (number): Total pages
|
||||
- `sync_mode` (string): Sync mode (immediate, deferred)
|
||||
- `device_info` (object): Device information
|
||||
- `koreader_version` (string): KOReader version
|
||||
- `device_model` (string): Device model identifier
|
||||
|
||||
**Response:**
|
||||
- `sync_status` (string): Sync status (accepted, processing)
|
||||
- `books_synced` (number): Number of books synced
|
||||
|
||||
**Status Codes:**
|
||||
- 202: Accepted - sync queued
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,23 @@
|
||||
info:
|
||||
name: Add Books to Kobo Shelf
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{baseURL}}/api/devices/{{deviceID}}/shelves'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"media_item_ids\": [\n \"{{bookUUID1"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{userToken
|
||||
|
||||
docs: |-
|
||||
## Add Books to Kobo Shelf
|
||||
|
||||
Add one or more books to a Kobo device shelf. Manages which books should be synced to a specific Kobo device. Supports multiple shelves for organization.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/{deviceID
|
||||
@@ -0,0 +1,40 @@
|
||||
info:
|
||||
name: Approve Device Registration
|
||||
type: http
|
||||
seq: 6
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/approve/{{registration_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Approve Device Registration
|
||||
|
||||
Approves a pending device registration request.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/approve/:registration_id
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Path Parameters:**
|
||||
- `registration_id` (string): Registration request UUID
|
||||
|
||||
**Response:**
|
||||
- Success message with approved device details
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Registration not found
|
||||
- 400: Invalid registration status
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"message": "Device registration approved",
|
||||
"device_id": "uuid",
|
||||
"device_name": "My Kobo"
|
||||
@@ -0,0 +1,55 @@
|
||||
info:
|
||||
name: Approve Registration - KOReader
|
||||
type: http
|
||||
seq: 13
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/approve/reg-uuid-123'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Approve KOReader Device Registration
|
||||
|
||||
Approves a pending KOReader device registration.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/approve/:registration_id
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `registration_id` (string): Example: `reg-uuid-123`
|
||||
|
||||
**Response:**
|
||||
- `registration_id` (string): Approved registration UUID
|
||||
- `device_id` (string): Generated device UUID
|
||||
- `device_name` (string): KOReader device name
|
||||
- `device_type` (string): `koreader`
|
||||
- `status` (string): `approved`
|
||||
- `access_token` (string): Device access token
|
||||
- `sync_endpoints` (object):
|
||||
- `bookmarks` (string): Bookmarks sync endpoint
|
||||
- `progress` (string): Progress sync endpoint
|
||||
- `highlights` (string): Highlights sync endpoint
|
||||
- `annotations` (string): Annotations sync endpoint
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Approved successfully
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Registration not found
|
||||
|
||||
**KOReader-Specific Features:**
|
||||
- Supports per-book SHA-256 based progress tracking
|
||||
- Syncs highlights with color and notes
|
||||
- Syncs bookmarks with locations and timestamps
|
||||
- Supports dictionary annotations
|
||||
- Can sync custom highlight colors
|
||||
|
||||
**After Approval:**
|
||||
- KOReader device can immediately sync
|
||||
- Device shows up in device list as "KOReader"
|
||||
- Access token is stored in device settings
|
||||
- Initial sync pulls down existing user data
|
||||
@@ -0,0 +1,60 @@
|
||||
info:
|
||||
name: Approve Registration - Kobo
|
||||
type: http
|
||||
seq: 14
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/approve/reg-uuid-456'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Approve Kobo Device Registration
|
||||
|
||||
Approves a pending Kobo e-reader device registration.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/approve/:registration_id
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `registration_id` (string): Example: `reg-uuid-456`
|
||||
|
||||
**Response:**
|
||||
- `registration_id` (string): Approved registration UUID
|
||||
- `device_id` (string): Generated device UUID
|
||||
- `device_name` (string): Kobo device name
|
||||
- `device_type` (string): `kobo`
|
||||
- `status` (string): `approved`
|
||||
- `access_token` (string): Device access token
|
||||
- `sync_endpoints` (object):
|
||||
- `bookmark_sync` (string): Bookmark sync URL
|
||||
- `markup_sync` (string): Markup/highlight sync URL
|
||||
- `metadata_sync` (string): Metadata sync URL
|
||||
- `kobo_features` (object):
|
||||
- `supports_shelves` (boolean): Kobo shelf support
|
||||
- `supports_dictionary` (boolean): Dictionary annotation support
|
||||
- `supports_statistics` (boolean): Reading statistics support
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Approved successfully
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Registration not found
|
||||
|
||||
**Kobo-Specific Features:**
|
||||
- Native Kobo sync protocol support
|
||||
- Shelves/collections sync
|
||||
- Reading statistics sync
|
||||
- Dictionary lookups with annotations
|
||||
- Book metadata sync
|
||||
- Pocket articles integration
|
||||
|
||||
**After Approval:**
|
||||
- Kobo device can use native sync feature
|
||||
- Device appears in Nickel (Kobo UI)
|
||||
- Sync runs automatically when connected
|
||||
- Shelves sync with collections
|
||||
- Reading progress syncs across devices
|
||||
@@ -0,0 +1,52 @@
|
||||
info:
|
||||
name: Check Pending Registration
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/register/status'
|
||||
auth: none
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
registration_id: registration-uuid-here
|
||||
|
||||
docs: |-
|
||||
## Check Registration Status
|
||||
|
||||
Checks the current status of a device registration request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/register/status
|
||||
|
||||
**Authentication:** None
|
||||
|
||||
**Request Body:**
|
||||
- `registration_id` (string): UUID received from registration request
|
||||
|
||||
**Response:**
|
||||
- `registration_id` (string): The registration UUID
|
||||
- `status` (string): Current status
|
||||
- `pending`: Awaiting user approval
|
||||
- `approved`: Registration approved, device ready
|
||||
- `rejected`: Registration rejected by user
|
||||
- `expired`: Registration expired (not approved in time)
|
||||
- `device_name` (string): Name of the device
|
||||
- `device_type` (string): Type of device
|
||||
- `created_at` (string): Registration timestamp
|
||||
- `updated_at` (string): Last status update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Status retrieved successfully
|
||||
- 404: Registration ID not found
|
||||
- 400: Invalid registration ID format
|
||||
|
||||
**Polling Recommendations:**
|
||||
- Poll every 5-10 seconds while status is `pending`
|
||||
- Stop polling when status changes to `approved`, `rejected`, or `expired`
|
||||
- Use exponential backoff for mobile devices to save battery
|
||||
@@ -0,0 +1,11 @@
|
||||
info:
|
||||
name: Check Registration Status
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/register/status'
|
||||
auth: none
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"registration_id\": \"{{registrationId"
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Clear Kobo Shelf
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{baseURL}}/api/devices/{{deviceID}}/shelves/clear?shelf={{shelfName}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{userToken
|
||||
|
||||
docs: |-
|
||||
## Clear Kobo Shelf
|
||||
|
||||
Clear all books from a Kobo device shelf, or all shelves if no shelf name is specified.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/devices/{deviceID
|
||||
@@ -0,0 +1,55 @@
|
||||
info:
|
||||
name: Create Device File Alias
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"file_path\": \"/mnt/sd/books/my-book.kepub.epub\",\n \"\
|
||||
media_item_id\": \"{{media_item_id"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test_create_device_file_alias_success(status, headers, body) {\n if\
|
||||
\ (status !== 201 && status !== 200) {\n throw new Error(\"Expected status\
|
||||
\ 201 or 200, got \" + status);"
|
||||
|
||||
docs: |-
|
||||
## Create Device File Alias
|
||||
|
||||
Creates a new file alias for a device. File aliases map device-specific file paths to media items.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/:id/file-aliases
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `id` (string, required): Device UUID
|
||||
|
||||
**Request Body:**
|
||||
- `file_path` (string, required): Device-specific file path
|
||||
- `media_item_id` (string, required): Media item UUID to link to
|
||||
|
||||
**Response:** Created file alias object
|
||||
- `id` (string): Alias UUID
|
||||
- `device_id` (string): Device UUID
|
||||
- `file_path` (string): Device-specific file path
|
||||
- `media_item_id` (string): Associated media item UUID
|
||||
- `created_at` (string): Creation timestamp
|
||||
- `updated_at` (string): Last update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Created
|
||||
- 200: Success
|
||||
- 400: Invalid request body
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Delete Device
|
||||
type: http
|
||||
seq: 6
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Delete Device
|
||||
|
||||
Deletes a device and unregisters it from the user's account.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/devices/{deviceId
|
||||
@@ -0,0 +1,58 @@
|
||||
info:
|
||||
name: Disable Device Sync
|
||||
type: http
|
||||
seq: 8
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/devices/{{device_id}}'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body:
|
||||
type: json
|
||||
json:
|
||||
device_name: My Kobo Clara
|
||||
sync_enabled: false
|
||||
auto_sync: false
|
||||
sync_frequency_minutes: 30
|
||||
|
||||
docs: |-
|
||||
## Disable Device Sync
|
||||
|
||||
Disables synchronization for a specific device.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/devices/:device_id
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): UUID of the device
|
||||
|
||||
**Request Body:**
|
||||
- `device_name` (string, optional): Device name
|
||||
- `sync_enabled` (boolean): Must be `false`
|
||||
- `auto_sync` (boolean): Should be `false`
|
||||
- `sync_frequency_minutes` (integer, optional): Any value (sync disabled)
|
||||
|
||||
**Response:**
|
||||
- `id` (string): Device UUID
|
||||
- `device_name` (string): Device name
|
||||
- `sync_enabled` (boolean): `false`
|
||||
- `auto_sync` (boolean): `false`
|
||||
- `message` (string): Confirmation message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Sync disabled successfully
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Device not found
|
||||
|
||||
**Use Cases:**
|
||||
- Temporarily disable sync for troubleshooting
|
||||
- Stop sync for a lost or stolen device
|
||||
- Disable sync before selling or giving away device
|
||||
- Prevent data usage on limited connections
|
||||
@@ -0,0 +1,44 @@
|
||||
info:
|
||||
name: Get Device File Aliases
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
|
||||
auth: inherit
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test_get_device_file_aliases_success(status, headers, body) {\n if (status\
|
||||
\ !== 200) {\n throw new Error(\"Expected status 200, got \" + status);"
|
||||
|
||||
docs: |-
|
||||
## Get Device File Aliases
|
||||
|
||||
Retrieves all file aliases for a specific device. File aliases are used to map device-specific file paths to media items.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/:id/file-aliases
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `id` (string, required): Device UUID
|
||||
|
||||
**Response:** Array of file alias objects
|
||||
- `id` (string): Alias UUID
|
||||
- `device_id` (string): Device UUID
|
||||
- `file_path` (string): Device-specific file path
|
||||
- `media_item_id` (string): Associated media item UUID
|
||||
- `created_at` (string): Creation timestamp
|
||||
- `updated_at` (string): Last update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
- 500: Internal server error
|
||||
@@ -0,0 +1,45 @@
|
||||
info:
|
||||
name: Get Device Details
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Device Details
|
||||
|
||||
Retrieves detailed information about a specific device.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/:device_id
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): UUID of the device
|
||||
|
||||
**Response:**
|
||||
- `id` (string): Device UUID
|
||||
- `device_name` (string): Device name
|
||||
- `device_type` (string): `kobo`, `koreader`, or `web`
|
||||
- `device_identifier` (string): Unique identifier
|
||||
- `sync_enabled` (boolean): Sync status
|
||||
- `auto_sync` (boolean): Auto-sync setting
|
||||
- `sync_frequency_minutes` (integer): Sync interval
|
||||
- `last_synced_at` (string): Last sync timestamp
|
||||
- `sync_stats` (object): Sync statistics
|
||||
- `total_syncs` (integer): Number of successful syncs
|
||||
- `last_sync_status` (string): Status of last sync
|
||||
- `bytes_synced` (integer): Total data transferred
|
||||
- `created_at` (string): Registration timestamp
|
||||
- `updated_at` (string): Last update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (device belongs to different user)
|
||||
- 404: Device not found
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Get Kobo Shelf Books
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{baseURL}}/api/devices/{{deviceID}}/shelves?shelf={{shelfName}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{userToken
|
||||
|
||||
docs: |-
|
||||
## Get Kobo Shelf Books
|
||||
|
||||
Get all books on a Kobo device shelf, optionally filter by shelf name.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/{deviceID
|
||||
@@ -0,0 +1,12 @@
|
||||
info:
|
||||
name: Initiate Device Registration
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/register'
|
||||
auth: none
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_name\": \"My Kindle Paperwhite\",\n \"device_type\"\
|
||||
: \"koreader\",\n \"device_identifier\": \"kindle-pw5-hardware-id-12345\""
|
||||
@@ -0,0 +1,41 @@
|
||||
info:
|
||||
name: List User Devices
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## List User Devices
|
||||
|
||||
Retrieves all registered devices for the authenticated user.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Response:**
|
||||
- Array of device objects:
|
||||
- `id` (string): Device UUID
|
||||
- `device_name` (string): Human-readable device name
|
||||
- `device_type` (string): `kobo`, `koreader`, or `web`
|
||||
- `device_identifier` (string): Unique device identifier
|
||||
- `sync_enabled` (boolean): Whether sync is active
|
||||
- `auto_sync` (boolean): Whether automatic sync is enabled
|
||||
- `sync_frequency_minutes` (integer): Sync interval in minutes
|
||||
- `last_synced_at` (string): Last successful sync timestamp
|
||||
- `created_at` (string): Registration timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
|
||||
**Usage:**
|
||||
- Display user's devices in account settings
|
||||
- Allow users to manage sync settings per device
|
||||
- Show last sync time for each device
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user