Ga naar hoofdinhoud

De API van server Calibre — genoteerd

Technisch dossier en ontwerp. Dit document bewaart de studies en de beoogde architectuur. Mogelijk zijn niet alle beschreven functies beschikbaar; de gebruikershandleiding en de code specificeren de huidige bewerking.

Verklaring afgelegd op 30 oktober 2026 vanuit de broncode van Calibre (src/calibre/srv/), geen documentatie: er bestaat geen. Geïmplementeerd en gedekt door tests in Packages/Core/Sources/CalibreKit.


1. Waarschuwing, afkomstig van de beheerder zelf​

Gevraagd naar documentatie voor API /ajax, Kovid Goyal antwoordt dat het niet bestaat, dat dit oppervlak niet bestaat noch openbaar, noch stabiel, en dat je de bron moet lezen. Gevolgen behouden in CalibreKit :

  • alle decodering is tolerant — een ontbrekend, onverwacht of null zorgt er nooit voor dat een bibliotheekvermelding mislukt;
  • de aard van de server wordt gedetecteerd bij verbinding (detectFlavor()), omdat Calibre-Web op alles 404 antwoordt /ajax/* en biedt alleen OPDS;
  • OPDS blijft de terugvalroute, gestandaardiseerd en stabiel;
  • -tests bevriezen de werkelijke bytevormen, zodat een upgrade van Calibre een test verbreekt in plaats van de applicatie.

2. Drie conventies voor de naamgeving van de bibliotheek​

Dit is de belangrijkste valkuil van deze API. Het wordt eenmaal ingevoerd gecodeerd CalibreClient.url(path:query:libraryInQuery:) en geverifieerd door vier tests.

RoutefamilieWaar gaat het heen library_id
/ajax/…, /get/…padcomponent — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…queryparameter — ?library_id=Calibre_Library
/book-…-last-read-position/…padcomponent, nogmaals

Ingecheckt srv/utils.py : get_library_data() bed rd.query.get('library_id').


3. Catalogus — srv/ajax.py​

WegRetourzendingen
GET /ajax/library-info{library_map, default_library} — dient ook als serveraardtest
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, parameters query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3woordenboek geïndexeerd op identificatie, null voor een verboden boek
GET /ajax/book/{id}/{library}de metadata van een boek
GET /ajax/categories/{library}categorieën van het eerste niveau
GET /ajax/category/{nom}/{library}de inhoud van een categorie, gepagineerd
GET /ajax/books_in/{cat}/{item}/{library}de identificatiegegevens van een categorie

Twee valkuilen bij het decoderen, beide gedekt door tests:

De ID staat niet in het onderwerp. /ajax/books indexeert zijn woordenboek op identificatie en herhaalt het niet binnenin. CalibreKit injecteert het via de userInfo van de decoder.

0101-01-01T00:00:00+00:00 betekent “geen datum”. Het is de schildwacht UNDEFINED_DATE van Calibre. Naïef gedecodeerd levert het een boek op dat in de oudheid is gepubliceerd. CalibreDate brengt het terug naar nil.


4. Conversie — srv/convert.py​

Dit is de ontdekking die de architectuur verandert: de server Calibre converteert, door HTTP.

WegMethodeRol
/conversion/book-data/{id}KRIJGinvoerformaten, uitvoerformaten, geaccepteerde opties
/conversion/start/{id}POSTlichaam {input_fmt, output_fmt, options} → retourneert een taak-ID
/conversion/status/{job}POST{running, percent, msg} vervolgens de terminalstatus; ?abort_job=1 onderbreekt

Details vermeld in de bron, en allemaal belangrijk voor gebruik:

  • Alleen POST (receive_data_methods = {'POST'}). Een GET wordt geweigerd.
  • input_fmt moet zijn een formaat dat het boek daadwerkelijk heeft : De server bouwt vanaf daar het bronpad op en gooit de rest weg. Hij wacht er in hoofdletters op, output_fmt in kleine letters.
  • Status wordt verbruikt bij eerste terminallezing : del conversion_jobs[job_id], dan cleanup() in een finally. Je kunt de conclusie maar één keer lezen. En alleen de gebruiker die de taak heeft gestart, in dezelfde bibliotheek, kan deze opvragen. CalibreKit.convert(…) omhult de sondelus, zodat geen enkele beller erover hoeft na te denken.
  • Het productformaat wordt toegevoegd aan het boek in de bibliotheek : db.add_format(book_id, fmt, output_path). Het werk wordt dus maar één keer gedaan en alle apparaten profiteren er dan van. /get/EPUB/{id}.
  • Receptbestanden worden geweigerd (code-uitvoering) en een lijst met opties is verboden door het netwerk.

De volledige route, zoals CalibreKit implementeert het:

GET /conversion/book-data/42?library_id=L → entrées : AZW3, PDF ; sorties : epub, mobi, …
POST /conversion/start/42?library_id=L → 17
{"input_fmt":"AZW3","output_fmt":"epub","options":{}}
POST /conversion/status/17?library_id=L → {"running":true,"percent":10,"msg":"Lecture"}
POST /conversion/status/17?library_id=L → {"running":false,"ok":true,"fmt":"epub","size":912345}
GET /get/EPUB/42/L → le fichier, désormais dans la bibliothèque

5. Leespositie en annotaties — srv/books.py​

Calibre synchroniseert al afspeelposities, serverzijde.

WegMethodeRol
/book-get-last-read-position/{library}/{id}:{FMT}KRIJGbekende posities, per apparaat
/book-set-last-read-position/{library}/{id}/{FMT}POSTslaat op {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}KRIJGhoogtepunten en notities
/book-manifest/{id}/{FMT}KRIJGserver normaliseert elk formaat in manifest voor zijn eigen lezer
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}KRIJGeen gestandaardiseerde boekenbron
/book-get-storage/{library}/{id}/{FMT}KRIJGopslagstatus

Twee gevolgen voor Podbook:

We kunnen de kranten achterlaten .jsonl beschreven in de initiële specificaties, althans als hoofdmechanisme: Calibre heeft al een positie per apparaat, per boek en per formaat. De logboeken zijn nog steeds nuttig voor wat Calibre niet weet: de positie in de audio, het woordenschatboekje.

/book-manifest is een sneltoets om te evalueren. De server weet al hoe hij elk formaat moet omzetten in een gestandaardiseerde structuur voor zijn webreder. Dit dekt een deel van wat BookKit moest doen. Moet worden onderzocht voordat de parser wordt geschreven: het formaat van het manifest is intern in Calibre en moet daarom worden behandeld als het oppervlak /ajax, met voorzichtigheid.

srv/kosync.py stelt bovendien het KOReader-synchronisatieprotocol beschikbaar (/kosync/users/auth, /kosync/syncs/progress), een andere mogelijke route, al overgenomen door andere lezers.


6. Zoeken in volledige tekst — srv/fts.py​

WegMethodeRol
/fts/searchKRIJGzoeken in de tekst van de boeken, niet alleen metagegevens
/fts/snippets/{book_ids}KRIJGextraheert met context
/fts/reindex, /fts/indexing, /fts/disablePOSTindexcontrole

De index moet aan de serverzijde zijn ingeschakeld. Podbook hoeft de bibliotheek dus niet zelf te indexeren voor globaal zoeken — alleen voor boeken die buiten Calibre zijn geïmporteerd.


7. Schrijven in de bibliotheek — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L voert een subcommando uit calibredb op de server. Het is de ondersteunde manier om te schrijven: metadata.db tolereert geen tweede editor.

Beschikbare opdrachten: add, add_format, remove, remove_format, set_metadata, set_custom, add_custom_column, remove_custom_column, custom_columns, annotations, search, list, list_categories, items, notes, data_files, embed_metadata, export, catalog, saved_searches, virtual_libraries, fts_index, fts_search, check_library, backup_metadata, restore_database, clone, trash.

set_custom Met kunt u de verwerkingsstatus van Podbook in een aangepaste kolom schrijven #podbook, zichtbaar vanaf Calibre, correct.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standaard, stabiel, aangekondigd in Hallo op het lokale netwerk. Het is de terugtrekking wanneer /ajax is er niet — vooral niet tegen Calibre-Web.


9. Wat dit verandert voor Podbook​

Initiële hypotheseRealiteit
Er moet een MOBI-parser worden geschrevenOnwaar vanaf v1: ebook-convert was al genoeg
Ombouw vereist workshop over MacOnwaar : calibre-server converteert naar HTTP. iPad-verzoeken, de server werkt, de bibliotheek is verrijkt
Podbook moet zijn positietiming uitvindenGedeeltelijk onwaar : Calibre bevat al één, per apparaat
Podbook moet indexeren voor globaal zoekenOnwaar : /fts/search bestaat
metadata.db alleen lezen, schrijven niet mogelijkOnwaar : /cdb/cmd/… is de officiële schrijfroute
De API /ajax vormt een solide basisOnwaar : niet openbaar, niet stabiel. Vandaar de tolerante decodering, natuurdetectie en fallback OPDS

Nog steeds waar: met DRM beveiligde bestanden kunnen niet worden geopend en er moet ergens een Calibre-server actief zijn voordat conversie en globaal zoeken beschikbaar zijn.