Feat/komga api #2071

farfromrefug · 2025-12-31T08:21:18Z

🚀 Pull Request

📝 Description

This PR adds a new Komga compatible API.

This is draft for now. I need to clean the workflow change i had to implement to get github packages docker releases.
Have to see about the doc.

🛠️ Changes Implemented

Added the new Komga API, added backend API and frontend setting to enable it
there is a new clean query parameter not supported by the official komga API. When enabled the API results will be cleared of unused/unnecessary fields for apps supporting it (koma for one). null fields, empy arrays, ...Lock fields are not returned

🧪 Testing Strategy

I use the API directly with a Komga plugin for Mihon. I am also writing a Booklore plugin with more features

⚠️ Required Pre-Submission Checklist

Code adheres to project style guidelines and conventions
Branch synchronized with latest develop branch
Automated unit/integration tests added/updated to cover changes
All tests pass locally (./gradlew test for backend)
Manual testing completed in local development environment
Flyway migration versioning follows correct sequence (if database schema modified)
Documentation pull request submitted to booklore-docs (required for features or enhancements that introduce user-facing or visual changes)

Merge Develop into Master for release

Merge develop into master for release

Merge Develop into Master for Release

Merge pull request booklore-app#847 from booklore-app/develop

Try fixing versioning #2

Merge develop into master for the release

Merge develop into the master for release

Merge develop into master for release

Merge develop itno master for the release

Merge develop into master for the release

beudbeud · 2026-01-06T17:19:08Z

@farfromrefug i haven't see new commit

beudbeud · 2026-01-06T17:31:51Z

Do you manage reading progress ?
https://komga.org/docs/openapi/mihon

farfromrefug · 2026-01-06T20:04:09Z

@beudbeud my bad pushed now. About reading progress no it is not implemented. But it seems booklore already have an api for this. So it is a matter of integrating this into other apps.

beudbeud · 2026-01-06T20:09:05Z

thanks it's work now

About reading progression it will be difficult i think because we use not internal user of Booklore just the OPDS user

beudbeud · 2026-01-06T20:09:52Z

For me, all work perfectly and can be merge

farfromrefug · 2026-01-06T20:30:34Z

thanks it's work now

About reading progression it will be difficult i think because we use not internal user of Booklore just the OPDS user

good point. Then i could implement komga like progress api in the future. TBh i dont use it

- 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>

Remove unused optimization queries that don't align with application-level series grouping logic Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com>

- 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>

…erformance Optimize Komga API series listing with database-level query optimization

farfromrefug · 2026-01-07T11:21:53Z

@beudbeud i was not really happy with performances in this PR, so i made some changes for faster db requests. if you could test again that would be great

@acx10 could i ask for this to be reviewed now? I am afraid some new migrations will come which will conflict with this PR migration numbers
EDIT: actually it already happened :s 84 is now taken

beudbeud · 2026-01-07T13:07:04Z

i have issue now about migration

booklore  | Caused by: org.flywaydb.core.api.FlywayException: Found more than one migration with version 84
booklore  | Offenders:
booklore  | -> /nested:/app/app.jar/!BOOT-INF/classes/!/db/migration/V84__Assign_admin_users_to_all_libraries.sql (SQL)
booklore  | -> /nested:/app/app.jar/!BOOT-INF/classes/!/db/migration/V84__Add_komga_api_enabled_setting.sql (SQL)
booklore  | 	at org.flywaydb.core.internal.resolver.CompositeMigrationResolver.checkForIncompatibilities(CompositeMigrationResolver.java:92) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.resolver.CompositeMigrationResolver.doFindAvailableMigrations(CompositeMigrationResolver.java:125) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.resolver.CompositeMigrationResolver.resolveMigrations(CompositeMigrationResolver.java:112) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.resolver.CompositeMigrationResolver.resolveMigrations(CompositeMigrationResolver.java:118) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.info.MigrationInfoServiceImpl.refresh(MigrationInfoServiceImpl.java:86) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.command.DbValidate.lambda$validate$0(DbValidate.java:112) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.jdbc.TransactionalExecutionTemplate.execute(TransactionalExecutionTemplate.java:59) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.internal.command.DbValidate.validate(DbValidate.java:105) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.Flyway.doValidate(Flyway.java:529) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.Flyway.lambda$migrate$1(Flyway.java:199) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.FlywayExecutor.execute(FlywayExecutor.java:210) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.flywaydb.core.Flyway.migrate(Flyway.java:188) ~[flyway-core-11.7.2.jar!/:na]
booklore  | 	at org.springframework.boot.autoconfigure.flyway.FlywayMigrationInitializer.afterPropertiesSet(FlywayMigrationInitializer.java:66) ~[spring-boot-autoconfigure-3.5.8.jar!/:3.5.8]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1873) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1822) ~[spring-beans-6.2.14.jar!/:6.2.14]

booklore  | Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'jpaSharedEM_entityManagerFactory': Cannot resolve reference to bean 'entityManagerFactory' while setting constructor argument
booklore  | 	at org.springframework.beans.factory.support.BeanDefinitionValueResolver.resolveReference(BeanDefinitionValueResolver.java:377) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.BeanDefinitionValueResolver.resolveValueIfNecessary(BeanDefinitionValueResolver.java:135) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.ConstructorResolver.resolveConstructorArguments(ConstructorResolver.java:691) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.ConstructorResolver.instantiateUsingFactoryMethod(ConstructorResolver.java:513) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.instantiateUsingFactoryMethod(AbstractAutowireCapableBeanFactory.java:1375) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBeanInstance(AbstractAutowireCapableBeanFactory.java:1205) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:569) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(AbstractAutowireCapableBeanFactory.java:529) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractBeanFactory.lambda$doGetBean$0(AbstractBeanFactory.java:339) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.DefaultSingletonBeanRegistry.getSingleton(DefaultSingletonBeanRegistry.java:373) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:337) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:202) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	at org.springframework.beans.factory.support.BeanDefinitionValueResolver.resolveReference(BeanDefinitionValueResolver.java:365) ~[spring-beans-6.2.14.jar!/:6.2.14]
booklore  | 	... 110 common frames omitted
booklore  | Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer' defined in class path resource [org/springframework/boot/autoconfigure/flyway/FlywayAutoConfiguration$FlywayConfiguration.class]: Found more than one migration with version 84

farfromrefug · 2026-01-07T13:38:53Z

@beudbeud yes this is normal as migrations have changed in main branch and conflict with this branch.
You either have to reset your db and start from scratch or manually modify the booklore db (which i am doing right now).
I am sorry there is nothing i can do about that

beudbeud · 2026-01-07T13:41:24Z

@farfromrefug can you give me explain for update manually the database?

farfromrefug · 2026-01-07T13:49:58Z

@beudbeud you need to open the mariadb database (connect to it) then open the flyway_schema_history table and fix the errors as per the messages you get. Which means changing the checksum. Then when you run it again change the description as per errors.

beudbeud · 2026-01-07T14:10:02Z

it's normal to have that ?

farfromrefug · 2026-01-07T14:17:25Z

@beudbeud no it was not. sorry pushed and fix. You still have to fix your db

beudbeud · 2026-01-07T14:25:17Z

i fixed the database, it's work nice

acx10 · 2026-01-08T18:55:50Z

@farfromrefug The code looks good at a glance. I’ll review it thoroughly this weekend.
In the meantime, could you please add documentation to booklore-docs with screenshots and all the necessary details? Thanks!

farfromrefug · 2026-01-09T15:58:40Z

@acx10 awesome thank you! here you go booklore-app/booklore-docs#23

# Conflicts: # booklore-api/src/main/java/com/adityachandel/booklore/repository/BookRepository.java

acx10 · 2026-01-09T21:04:24Z

booklore-api/src/main/java/com/adityachandel/booklore/config/security/SecurityConfig.java

            "/api/v1/auth/**",         // Login and token refresh endpoints (must remain public)
            "/api/v1/public-settings", // Public endpoint for checking OIDC or other app settings
-            "/api/v1/setup/**",        // Setup wizard endpoints (must remain accessible before initial setup)
-            "/api/v1/healthcheck/**"   // Healthcheck endpoints (must remain accessible for Docker healthchecks)


Can you please add this back

"/api/v1/healthcheck/**"

acx10 · 2026-01-09T21:06:44Z

booklore-api/src/main/java/com/adityachandel/booklore/config/JacksonConfig.java

+ * Jackson configuration for Komga API clean mode.
+ */
+@Configuration
+public class JacksonConfig {


This config registers a @primary ObjectMapper and applies a BeanSerializerModifier globally, which will affect serialization across the entire app. That’s pretty risky.
Can we scope this to a dedicated ObjectMapper and only use it where needed (e.g., specific endpoints or services) instead of changing global behavior?

acx10 · 2026-01-09T21:07:48Z

booklore-api/src/main/java/com/adityachandel/booklore/config/security/SecurityConfig.java


    @Bean
    @Order(2)
+    public SecurityFilterChain komgaBasicAuthSecurityChain(HttpSecurity http) throws Exception {


Do we really need a separate SecurityFilterChain for this? Can we reuse or extend the existing security configuration instead of introducing another one? It would be good to understand what this chain adds that the current setup doesn’t cover.

i was just "copying" OPDS api security chain. You want me to use the same one? I am ok with that but wouldn't that mean that the WWW-Authenticate header would report the OPDS realm?

acx10 · 2026-01-09T21:09:15Z

booklore-api/src/main/java/com/adityachandel/booklore/controller/KomgaController.java

+        "resulting in smaller and cleaner JSON payloads.")
+@Slf4j
+@RestController
+@RequestMapping(value = "/komga/api", produces = "application/json")


Can we change the base path to something like /api/komga/v1? That way we can avoid having to update nginx.conf and keep the routing consistent with the existing API structure.

@acx10 actually this is problematic to be compatible with komga clients. They all use /api/komga/v1 by happending to the host. If we change that none of them will work :s

acx10 added 30 commits August 8, 2025 20:03

Merge pull request booklore-app#847 from booklore-app/develop

62e91f1

Merge Develop into Master for release

Merge pull request booklore-app#867 from booklore-app/develop

6bd2a10

Merge Develop into Master for release

Merge pull request booklore-app#877 from booklore-app/develop

0ea8292

Merge Develop into Master for release

Merge pull request booklore-app#887 from booklore-app/develop

b612fb8

Merge Develop into Master for release

Merge pull request booklore-app#911 from booklore-app/develop

ef02182

Merge Develop into Master for release

Merge pull request booklore-app#913 from booklore-app/develop

040970a

Merge Develop into Master for release

Merge pull request booklore-app#965 from booklore-app/develop

7ce2f80

Merge develop into master for release

Merge pull request booklore-app#988 from booklore-app/develop

3717d6e

Merge develop into master for release

Merge pull request booklore-app#989 from booklore-app/develop

7e9bff4

Merge develop into master for release

Merge pull request booklore-app#1023 from booklore-app/develop

b1ad4c0

Merge Develop into Master for Release

Merge pull request booklore-app#1025 from booklore-app/develop

9dd645f

Merge pull request booklore-app#847 from booklore-app/develop

Merge pull request booklore-app#1029 from booklore-app/develop

9f375b5

Merge pull request booklore-app#847 from booklore-app/develop

Merge pull request booklore-app#1031 from booklore-app/develop

fc0b62e

Try fixing versioning #2

Merge pull request booklore-app#1049 from booklore-app/develop

b02d670

Merge develop into master for the release

Merge pull request booklore-app#1065 from booklore-app/develop

dec0fb7

Merge develop into master for the release

Merge pull request booklore-app#1072 from booklore-app/develop

f9908e3

Merge develop into master for the release

Merge pull request booklore-app#1090 from booklore-app/develop

c7c2865

Merge develop into master for the release

Merge pull request booklore-app#1117 from booklore-app/develop

a502028

Merge develop into master for the release

Merge pull request booklore-app#1138 from booklore-app/develop

65bcc71

Merge develop into master for the release

Merge pull request booklore-app#1162 from booklore-app/develop

ce5cb50

Merge develop into master for the release

Merge pull request booklore-app#1170 from booklore-app/develop

ed81690

Merge develop into master for the release

Merge pull request booklore-app#1191 from booklore-app/develop

2159c5f

Merge develop into master for the release

Merge pull request booklore-app#1207 from booklore-app/develop

5485de7

Merge develop into master for the release

Merge pull request booklore-app#1245 from booklore-app/develop

f782f85

Merge develop into master for the release

Merge pull request booklore-app#1255 from booklore-app/develop

5811b19

Merge develop into the master for release

Merge pull request booklore-app#1280 from booklore-app/develop

fe2be3e

Merge develop into the master for release

Merge pull request booklore-app#1294 from booklore-app/develop

50237f8

Merge develop into master for release

Merge pull request booklore-app#1330 from booklore-app/develop

efdf49b

Merge develop into master for release

Merge pull request booklore-app#1370 from booklore-app/develop

30bdd85

Merge develop itno master for the release

Merge pull request booklore-app#1387 from booklore-app/develop

e109ada

Merge develop into master for the release

farfromrefug added 2 commits January 6, 2026 21:01

chore: fix seriesTitle in ungrouped unknowns

c7c5dc1

Merge remote-tracking branch 'origin/feat/komga_api' into feat/komga_api

3a2f22e

Copilot AI and others added 6 commits January 6, 2026 20:41

Initial plan

1633ee6

Clean up unused database query methods in BookRepository

3adb622

Remove unused optimization queries that don't align with application-level series grouping logic Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com>

Merge pull request #10 from farfromrefug/copilot/optimize-komga-api-p…

8c05e77

…erformance Optimize Komga API series listing with database-level query optimization

Merge branch 'booklore-app:develop' into feat/komga_api

f578ce6

chore: migration fix from merge

d391c28

acx10 added the feature Addition of new functionality label Jan 8, 2026

farfromrefug mentioned this pull request Jan 9, 2026

fix: new komga API doc booklore-app/booklore-docs#23

Open

farfromrefug added 2 commits January 9, 2026 16:59

Merge remote-tracking branch 'upstream/master' into feat/komga_api

9bee27d

Merge remote-tracking branch 'upstream/develop' into feat/komga_api

ce0a8a2

# Conflicts: # booklore-api/src/main/java/com/adityachandel/booklore/repository/BookRepository.java

acx10 requested changes Jan 9, 2026

View reviewed changes

Uh oh!

Feat/komga api #2071

Are you sure you want to change the base?

Feat/komga api #2071

Uh oh!

Conversation

farfromrefug commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Pull Request

📝 Description

🛠️ Changes Implemented

🧪 Testing Strategy

⚠️ Required Pre-Submission Checklist

Uh oh!

beudbeud commented Jan 6, 2026

Uh oh!

beudbeud commented Jan 6, 2026

Uh oh!

farfromrefug commented Jan 6, 2026

Uh oh!

beudbeud commented Jan 6, 2026

Uh oh!

beudbeud commented Jan 6, 2026

Uh oh!

farfromrefug commented Jan 6, 2026

Uh oh!

farfromrefug commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

beudbeud commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

farfromrefug commented Jan 7, 2026

Uh oh!

beudbeud commented Jan 7, 2026

Uh oh!

farfromrefug commented Jan 7, 2026

Uh oh!

beudbeud commented Jan 7, 2026

Uh oh!

farfromrefug commented Jan 7, 2026

Uh oh!

beudbeud commented Jan 7, 2026

Uh oh!

acx10 commented Jan 8, 2026

Uh oh!

farfromrefug commented Jan 9, 2026

Uh oh!

acx10 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

acx10 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

acx10 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

farfromrefug Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

acx10 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

farfromrefug Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

farfromrefug commented Dec 31, 2025 •

edited

Loading

farfromrefug commented Jan 7, 2026 •

edited

Loading

beudbeud commented Jan 7, 2026 •

edited

Loading