mirror of
https://github.com/adityachandelgit/BookLore.git
synced 2026-02-18 03:07:40 +01:00
Feat/komga api (#2071)
* Implement Komga API endpoints with OPDS authentication Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Add database migration and documentation for Komga API Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Address code review comments - improve performance and maintainability Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * chore: update with main develop * chore: log cleanup * chore: fixed switch with missing types * chore: missing case * Merge pull request #4 from farfromrefug/copilot/fix-500-error-on-books-api Fix NPE in Komga books API when pageCount is null and add unpaged parameter * Add collections endpoint and page download with PNG conversion support Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Address code review feedback for better resource management and error messages Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Fix convert parameter to match specification (convert=png) Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * chore: renamed migration * chore: migration * chore: migration fix * chore: should work now * chore: settings * chore: working with mihon * Initial plan * Add clean query parameter for Komga API endpoints Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Address code review comments - remove unused imports and add @Primary annotation Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Add demo test to illustrate clean mode effectiveness Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Support both ?clean and ?clean=true syntax Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Filter out empty arrays in clean mode Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * chore: missing field * chore: missing field * chore: fix error with missing number * fix: added groupUnknown API parameters to sort by "Unknown Series" (true by default) * Initial plan * Convert groupUnknown from query parameter to Booklore setting Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Remove unused groupUnknown variables from service and mapper Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * chore: fix seriesTitle in ungrouped unknowns * Initial plan * Optimize Komga API performance for series listing - Optimize getAllSeries to only convert series on current page to DTOs - Optimize getBooksBySeries to fetch books only once (not twice) - Add database query methods for future optimizations - Update tests to work with new optimizations - All existing tests pass Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Clean up unused database query methods in BookRepository Remove unused optimization queries that don't align with application-level series grouping logic Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * Optimize getAllSeries to query distinct series names from database - Add database queries to fetch distinct series names directly (no need to load all books) - Add queries to fetch books only for specific series (when building DTOs) - Support both groupUnknown=true and groupUnknown=false modes - Add test to verify optimization works and books aren't loaded unnecessarily - Performance improvement: For 1000+ books grouped into 100+ series, now only queries series names (~100 rows) instead of loading all books (~1000+ rows), then loads books only for the current page (~20-50 books per series on page) Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com> * chore: migration fix from merge * chore: address comments * fix: handle getBookPage for PDF/CBX * chore: rename migration * chore: komga specific series queries fix * chore: komga tests fix * chore: front end komga tests --------- Co-authored-by: Aditya Chandel <8075870+adityachandelgit@users.noreply.github.com> Co-authored-by: ACX <8075870+acx10@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
This commit is contained in:
farfromrefuge
112
docs/Komga-API.md
Normal file
112
docs/Komga-API.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Komga API Support
|
||||
|
||||
Booklore provides a Komga-compatible API that allows you to use Komga clients (like Tachiyomi, Tachidesk, Komelia, etc.) to access your Booklore library.
|
||||
|
||||
## Features
|
||||
|
||||
The Komga API implementation in Booklore provides the following endpoints:
|
||||
|
||||
### Libraries
|
||||
- `GET /api/v1/libraries` - List all libraries
|
||||
- `GET /api/v1/libraries/{libraryId}` - Get library details
|
||||
|
||||
### Series
|
||||
- `GET /api/v1/series` - List series (supports pagination and library filtering)
|
||||
- `GET /api/v1/series/{seriesId}` - Get series details
|
||||
- `GET /api/v1/series/{seriesId}/books` - List books in a series
|
||||
- `GET /api/v1/series/{seriesId}/thumbnail` - Get series thumbnail
|
||||
|
||||
### Books
|
||||
- `GET /api/v1/books` - List all books (supports pagination and library filtering)
|
||||
- `GET /api/v1/books/{bookId}` - Get book details
|
||||
- `GET /api/v1/books/{bookId}/pages` - Get book pages metadata
|
||||
- `GET /api/v1/books/{bookId}/pages/{pageNumber}` - Get book page image
|
||||
- `GET /api/v1/books/{bookId}/file` - Download book file
|
||||
- `GET /api/v1/books/{bookId}/thumbnail` - Get book thumbnail
|
||||
|
||||
### Users
|
||||
- `GET /api/v2/users/me` - Get current user details
|
||||
|
||||
## Data Model Mapping
|
||||
|
||||
Booklore organizes books differently than Komga:
|
||||
|
||||
- **Komga**: Libraries → Series → Books
|
||||
- **Booklore**: Libraries → Books (with optional series metadata)
|
||||
|
||||
The Komga API layer automatically creates virtual "series" by grouping books with the same series name in their metadata. Books without a series name are grouped under "Unknown Series".
|
||||
|
||||
## Enabling the Komga API
|
||||
|
||||
1. Navigate to **Settings** in Booklore
|
||||
2. Find the **Komga API** section
|
||||
3. Toggle **Enable Komga API** to ON
|
||||
4. Click **Save**
|
||||
|
||||
## Authentication
|
||||
|
||||
The Komga API uses the same OPDS user accounts for authentication. To access the Komga API:
|
||||
|
||||
1. Create an OPDS user account in Booklore settings
|
||||
2. Use those credentials when configuring your Komga client
|
||||
|
||||
Authentication uses HTTP Basic Auth, the same as OPDS.
|
||||
|
||||
## Using with Komga Clients
|
||||
|
||||
### Tachiyomi / TachiyomiSY / TachiyomiJ2K
|
||||
|
||||
1. Install the Tachiyomi app
|
||||
2. Add a source → Browse → Sources → Komga
|
||||
3. Configure the source:
|
||||
- Server URL: `http://your-booklore-server/`
|
||||
- Username: Your OPDS username
|
||||
- Password: Your OPDS password
|
||||
|
||||
### Komelia
|
||||
|
||||
1. Install Komelia
|
||||
2. Add a server:
|
||||
- URL: `http://your-booklore-server/`
|
||||
- Username: Your OPDS username
|
||||
- Password: Your OPDS password
|
||||
|
||||
### Tachidesk
|
||||
|
||||
1. Install Tachidesk
|
||||
2. Add Komga extension
|
||||
3. Configure:
|
||||
- Server URL: `http://your-booklore-server/`
|
||||
- Username: Your OPDS username
|
||||
- Password: Your OPDS password
|
||||
|
||||
## Limitations
|
||||
|
||||
- Individual page extraction is not yet implemented; page requests return the book cover
|
||||
- Read progress tracking from Komga clients is not synchronized with Booklore
|
||||
- Not all Komga API endpoints are implemented (only the most commonly used ones)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cannot connect to server
|
||||
|
||||
- Ensure the Komga API is enabled in Booklore settings
|
||||
- Verify your OPDS credentials are correct
|
||||
- Check that your server is accessible from the client device
|
||||
|
||||
### Books not appearing
|
||||
|
||||
- Ensure books have metadata populated, especially series information
|
||||
- Try refreshing the library in your Komga client
|
||||
|
||||
### Authentication failures
|
||||
|
||||
- The Komga API uses OPDS user accounts, not your main Booklore account
|
||||
- Create an OPDS user in the Settings → OPDS section
|
||||
- Use those credentials in your Komga client
|
||||
|
||||
## API Compatibility
|
||||
|
||||
The Booklore Komga API aims to be compatible with Komga v1.x API. While not all endpoints are implemented, the core functionality needed for reading and browsing is supported.
|
||||
|
||||
For the complete Komga API specification, see: https://github.com/gotson/komga
|
||||
71
docs/komga-clean-mode.md
Normal file
71
docs/komga-clean-mode.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Komga API Clean Mode
|
||||
|
||||
## Overview
|
||||
The Komga API now supports a `clean` query parameter that allows clients to receive cleaner, more compact JSON responses.
|
||||
|
||||
## Usage
|
||||
|
||||
Add the `clean` query parameter to any Komga API endpoint. Both syntaxes are supported:
|
||||
|
||||
```
|
||||
# Using parameter without value
|
||||
GET /komga/api/v1/series?clean
|
||||
GET /komga/api/v1/books/123?clean
|
||||
GET /komga/api/v1/libraries?clean
|
||||
|
||||
# Using parameter with explicit true value
|
||||
GET /komga/api/v1/series?clean=true
|
||||
GET /komga/api/v1/books/123?clean=true
|
||||
GET /komga/api/v1/libraries?clean=true
|
||||
```
|
||||
|
||||
## Behavior
|
||||
|
||||
When the `clean` parameter is present (either `?clean` or `?clean=true`):
|
||||
|
||||
1. **Lock Fields Excluded**: All fields ending with "Lock" (e.g., `titleLock`, `summaryLock`, `authorsLock`) are removed from the response
|
||||
2. **Null Values Excluded**: All fields with `null` values are removed from the response
|
||||
3. **Empty Arrays Excluded**: All empty arrays/collections (e.g., empty `genres`, `tags`, `links`) are removed from the response
|
||||
4. **Metadata Fields**: Metadata fields like `summary`, `language`, and `publisher` that would normally default to empty strings or default values can now be `null` and thus filtered out
|
||||
|
||||
## Examples
|
||||
|
||||
### Without Clean Mode (default)
|
||||
```json
|
||||
{
|
||||
"title": "My Book",
|
||||
"titleLock": false,
|
||||
"summary": "",
|
||||
"summaryLock": false,
|
||||
"language": "en",
|
||||
"languageLock": false,
|
||||
"publisher": "",
|
||||
"publisherLock": false,
|
||||
"genres": [],
|
||||
"genresLock": false,
|
||||
"tags": [],
|
||||
"tagsLock": false
|
||||
}
|
||||
```
|
||||
|
||||
### With Clean Mode (`?clean` or `?clean=true`)
|
||||
```json
|
||||
{
|
||||
"title": "My Book"
|
||||
}
|
||||
```
|
||||
|
||||
All the Lock fields, empty strings, and null values are excluded, resulting in a much smaller response.
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Reduced Payload Size**: Significantly smaller JSON responses, especially important for mobile clients or slow connections
|
||||
- **Cleaner API**: Removes clutter from responses that clients typically don't need
|
||||
- **Backward Compatible**: Default behavior remains unchanged; opt-in via query parameter
|
||||
|
||||
## Implementation Details
|
||||
|
||||
- Works with all Komga API GET endpoints under `/komga/api/**`
|
||||
- Uses a custom Jackson serializer modifier with ThreadLocal context
|
||||
- Implemented via Spring interceptor that detects the query parameter
|
||||
- ThreadLocal is properly cleaned up after each request to prevent memory leaks
|
||||
Reference in New Issue
Block a user