API poslužitelja Calibre — anketa
Tehnička i dizajnerska dokumentacija. Ovaj dokument sadrži studije i predloženu arhitekturu. Nisu nužno dostupne sve opisane funkcije; korisnički priručnik i kod specificiraju trenutnu operaciju.
Anketa provedena 30. listopada 2026. iz izvornog koda Calibre (src/calibre/srv/), nema dokumentacije: ne postoji. Implementirano i pokriveno testovima u Packages/Core/Sources/CalibreKit.
1. Upozorenje, koje dolazi od samog održavatelja
Na pitanje o dokumentaciji za API /ajax, Kovid Goyal odgovara da ne postoji, da ova površina nije ni javna ni stabilna i da se izvorni kod mora pročitati. Posljedice navedene u CalibreKit :
- svo dekodiranje je tolerantno — nedostajuće, neočekivano polje ili
nullnikada ne uzrokuje neuspjeh popisa knjižnice; - priroda poslužitelja se otkriva pri grananju (
detectFlavor()), jer Calibre-Web vraća 404 na sve/ajax/*i nudi samo OPDS ; - OPDS ostaje rezervna opcija, koja je standardizirana i stabilna;
- testovi zamrzavaju stvarne oblike bajtova, tako da će nadogradnja verzije Calibre prekinuti test, a ne aplikaciju.
2. Tri konvencije za imenovanje biblioteke
Ovo je glavna zamka ovog API. Kodiran je jednom u CalibreClient.url(path:query:libraryInQuery:) i provjeren s četiri testa.
| Obitelj ruta | Kamo ide? library_id |
|---|---|
/ajax/…, /get/… | Komponenta puta — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | Parametar upita — ?library_id=Calibre_Library |
/book-…-last-read-position/… | Komponenta puta, ponovno |
Prijavljeno srv/utils.py : get_library_data() Čita rd.query.get('library_id').
3. Katalog — srv/ajax.py
| Ruta | Renderira |
|---|---|
GET /ajax/library-info | {library_map, default_library} — također služi kao test prirode poslužitelja |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametri query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | Rječnik Indeksirano ID-om, null Za zabranjenu knjigu |
GET /ajax/book/{id}/{library} | Metapodaci knjige |
GET /ajax/categories/{library} | Kategorije najviše razine |
GET /ajax/category/{nom}/{library} | Sadržaj kategorije, paginiran |
GET /ajax/books_in/{cat}/{item}/{library} | ID-ovi kategorije Kategorija |
Dvije zamke za dekodiranje, obje pokrivene s testovi:
Identifikator nije u objektu. /ajax/books indeksira svoj rječnik po identifikatoru i ne ponavlja ga unutar njega. CalibreKit ubrizgava ga putem userInfo dekodera.
0101-01-01T00:00:00+00:00 znači "nema datuma". Ovo je čuvar UNDEFINED_DATE od Calibre. Naivno dekodiran, stvara knjigu objavljenu u Antiquity. CalibreDate vraća ga na nil.
4. Konverzija — srv/convert.py
Ovo je otkriće koje mijenja arhitekturu: poslužitelj Calibre pretvara putem HTTP.
| Ruta | Metoda | Uloga |
|---|---|---|
/conversion/book-data/{id} | GET | Ulazni formati, izlazni formati, prihvaćene opcije |
/conversion/start/{id} | POST | Tijelo {input_fmt, output_fmt, options} → vraća radni identifikator |
/conversion/status/{job} | POST | {running, percent, msg} zatim stanje terminala; ?abort_job=1 prekidi |
Detalji preuzeti iz izvora, svi značajni u upotrebi:
- samo POST (
receive_data_methods = {'POST'}). GET zahtjev je odbijen. input_fmtmora biti format koji knjiga zapravo ima : poslužitelj gradi izvorni put odatle i odbacuje ostatak. Očekuje ga velikim slovima,output_fmtmalim slovima.- Status se konzumira pri prvom čitanju terminala :
del conversion_jobs[job_id], zatimcleanup()ufinally. Zaključak se može pročitati samo jednom. I samo korisnik koji je pokrenuo posao, u istoj biblioteci, može ga upitati.CalibreKit.convert(…)enkapsulira petlju ispitivanja tako da nijedan pozivatelj ne mora razmišljati o tome. - Proizvedeni format dodaje se knjizi u biblioteci :
db.add_format(book_id, fmt, output_path). Posao se stoga obavlja samo jednom, a svi uređaji tada imaju koristi od njega tako što/get/EPUB/{id}. - Datoteke recepata se odbacuju (izvršavanje koda), a popis opcija blokira mreža.
Potpuni put, kako je implementirano od strane CalibreKit :
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. Položaj čitanja i napomene — srv/books.py
Calibre već sinkronizira položaje čitanja na strani poslužitelja.
| Ruta | Metoda | Uloga |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | poznati položaji, po uređaju |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | sprema {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | istaknute dijelove i bilješke |
/book-manifest/{id}/{FMT} | GET | poslužitelj normalizira bilo koji format u manifest za vlastiti čitač |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | resurs iz normalizirane knjige |
/book-get-storage/{library}/{id}/{FMT} | GET | stanje pohrane |
Dvije posljedice za Podbook:
Zapisnici se mogu napustiti .jsonl opisano u početnim specifikacijama, barem kao glavni mehanizam: Calibre već ima poziciju po uređaju, po knjizi i po formatu. Zapisnici ostaju korisni za ono što Calibre ne zna - poziciju u audio zapisu, bilježnicu vokabulara.
/book-manifest je prečac za procjenu. Poslužitelj već zna kako transformirati bilo koji format u standardiziranu strukturu za svoj web čitač. To pokriva dio onoga što je BookKit trebao učiniti. To treba istražiti prije pisanja parsera: format manifesta je interni za Calibre, pa ga treba tretirati kao površinu /ajax, s oprezom.
srv/kosync.py također otkriva KOReader protokol sinkronizacije (/kosync/users/auth, /kosync/syncs/progress), još jedan mogući pristup, koji su već usvojili drugi čitači.
6. Pretraživanje cijelog teksta — srv/fts.py
| Ruta | Metoda | Uloga |
|---|---|---|
/fts/search | GET | pretražuje tekst knjiga, ne samo metapodatke |
/fts/snippets/{book_ids} | GET | izdvojene s kontekstom |
/fts/reindex, /fts/indexing, /fts/disable | POST | kontrola indeksa |
Indeks mora biti omogućen na strani poslužitelja. Podbook stoga ne treba indeksirati samu biblioteku za globalno pretraživanje — samo za knjige uvezene izvan Calibre.
7. Pisanje u biblioteku — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L izvršava podnaredbu calibredb na poslužitelju. Ovo je [ podržana metoda za pisanje: metadata.db ne tolerira drugog pisca.
Dostupne naredbe: 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 vam omogućuje uredno zapisivanje statusa obrade Podbook u prilagođeni stupac #podbook, vidljiv iz Calibre.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standardni, stabilan, oglašava se kao Bonjour na lokalnoj mreži. To je rezervna opcija kada /ajax nije dostupan — posebno kada Calibre-Web nije dostupan.
9. Što se time mijenja za Podbook
| Početna hipoteza | Stvarnost |
|---|---|
| Potrebno je napisati MOBI parser | Netočno iz v1: ebook-convert je već bilo dovoljno |
| Konverzija zahtijeva radionicu na Mac | Netočno : calibre-server pretvorio HTTP. iPad zahtjevi, poslužitelj radi, biblioteka raste |
| Podbook mora izmisliti svoju sinkronizaciju položaja | Djelomično netočno : Calibre već održava jednu, po uređaju |
| Podbook mora indeksirati za globalno pretraživanje | Netočno : /fts/search postoji |
metadata.db samo za čitanje, nije moguće pisanje | Netočno : /cdb/cmd/… je službena metoda pisanja |
API /ajax je solidna baza podataka | Netočno : nije javno, nije stabilno. Stoga tolerantno dekodiranje, otkrivanje prirode i rezerva OPDS |
Ostaje istinito: Datoteke zaštićene DRM-om neće se otvoriti, a poslužitelj Calibre mora negdje raditi da bi pretvorba i globalno pretraživanje bili dostupni.