Idi na glavni sadržaj

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 null nikada 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 rutaKamo 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​

RutaRenderira
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,3Rječ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.

RutaMetodaUloga
/conversion/book-data/{id}GETUlazni formati, izlazni formati, prihvaćene opcije
/conversion/start/{id}POSTTijelo {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_fmt mora biti format koji knjiga zapravo ima : poslužitelj gradi izvorni put odatle i odbacuje ostatak. Očekuje ga velikim slovima, output_fmt malim slovima.
  • Status se konzumira pri prvom čitanju terminala : del conversion_jobs[job_id], zatim cleanup() u finally. 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.

RutaMetodaUloga
/book-get-last-read-position/{library}/{id}:{FMT}GETpoznati položaji, po uređaju
/book-set-last-read-position/{library}/{id}/{FMT}POSTsprema {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETistaknute dijelove i bilješke
/book-manifest/{id}/{FMT}GETposlužitelj normalizira bilo koji format u manifest za vlastiti čitač
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETresurs iz normalizirane knjige
/book-get-storage/{library}/{id}/{FMT}GETstanje 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​

RutaMetodaUloga
/fts/searchGETpretražuje tekst knjiga, ne samo metapodatke
/fts/snippets/{book_ids}GETizdvojene s kontekstom
/fts/reindex, /fts/indexing, /fts/disablePOSTkontrola 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 hipotezaStvarnost
Potrebno je napisati MOBI parserNetočno iz v1: ebook-convert je već bilo dovoljno
Konverzija zahtijeva radionicu na MacNetočno : calibre-server pretvorio HTTP. iPad zahtjevi, poslužitelj radi, biblioteka raste
Podbook mora izmisliti svoju sinkronizaciju položajaDjelomično netočno : Calibre već održava jednu, po uređaju
Podbook mora indeksirati za globalno pretraživanjeNetočno : /fts/search postoji
metadata.db samo za čitanje, nije moguće pisanjeNetočno : /cdb/cmd/… je službena metoda pisanja
API /ajax je solidna baza podatakaNetoč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.