API endpoint: kramerius.php

Endpoint slouží pro dohledání UUID stránky v Krameriu podle vstupu z Wikidat, nebo pro dohledání informací o stránce podle jejího UUID.

Stav po migraci

• Runtime resolver je provozován ve FastAPI službě kramerius-api.
• Přes gateway zůstává kontrakt POST /kramerius/api beze změny (požadavek je routován do FastAPI).
• Soubor kramerius/api/kramerius.php slouží pro dokumentaci (GET /kramerius/api).
• Přímé POST volání na tento PHP skript není určeno pro API runtime.

URL a metoda

• URL: /kramerius/api
• Metoda POST: API lookup endpoint (Content-Type: application/json)
• Metoda GET bez query parametrů a bez body: vrátí tuto dokumentaci v HTML podobě (pro pohodlné otevření v prohlížeči)

Poznámka: GET s query parametry nebo s body není podporován a vrací 405.

Režim 1: Wikidatový lookup (wd + page)

Request body

Příklad requestu:

{
  "wd": "Q96613911",
  "page": "140",
  "volume": "3",
  "volume_years": "1849",
  "issue": "18",
  "issue_type": "",
  "issue_date": "1849-04-01",
  "supplement": "",
  "debug": false
}

Režim 2: Přímý UUID lookup (uuid)

Dohledá veškeré dostupné informace o stránce podle jejího UUID. Procházení hierarchie:

stránka → vydání → svazek → dokument.

Poznámka: pokud stránka leží ve větvi supplement, API u issue_uuid vrací přednostně UUID rodičovského čísla (periodicalitem), nikoli UUID samotné přílohy. Díky tomu zůstávají pole issue, issue_date a citace konzistentní.

Request body

Příklad requestu:

{
  "uuid": "35d64c24-9cf2-408b-9147-935f1323be20",
  "debug": false
}

Úspěšná odpověď

HTTP status: 200

Struktura odpovědi je stejná pro oba režimy (Wikidatový i UUID lookup):

{
  "ok": true,
  "selection_required": false,
  "results_meta": {
    "offset": 0,
    "batch_size": 25,
    "returned_count": 1,
    "minimum_total_count": 1,
    "has_more": false
  },
  "results": [
    {
      "api_base": "https://ndk.cz/search/api/v5.0",
      "view_url": "https://ndk.cz/uuid/uuid:35d64c24-9cf2-408b-9147-935f1323be20",
      "document_uuid": "ae811ecf-435d-11dd-b505-00145e5790ea",
      "volume_uuid": "b1a8ec04-435d-11dd-b505-00145e5790ea",
      "issue_uuid": "e5204673-435d-11dd-b505-00145e5790ea",
      "page_uuid": "35d64c24-9cf2-408b-9147-935f1323be20",
      "document": "Blahověst: Katolický týdenník pro Čechy, Morawany, Slowáky a Slezany",
      "volume_nr": "3",
      "volume_years": "1849",
      "issue": "18",
      "issue_type": "",
      "issue_date": "1849-04-01",
      "supplement": "",
      "page": "140",
      "page_label": "140",
      "citation": "Blahověst: Katolický týdenník pro Čechy, roč. 3 (1849), č. 18, 1. dubna 1849, str. 140"
    }
  ]
}

Poznámka: Pole debug_trace je vráceno pouze při debug=true, proto v běžné odpovědi s debug=false nebude přítomno.

Význam polí v results:

Poznámka k issue_uuid: u stránek z příloh (supplement) je issue_uuid normalizováno na rodičovské vydání (periodicalitem), pokud je v metadata kontextu dostupné.

Poznámka: u textových příloh může API při nedohledání přílohy v přesně zadaném čísle projít i další kandidátní čísla ve stejném ročníku a vybrat to, které přílohu skutečně obsahuje.

Sémantika selection_required

Ideální výsledek API je právě jedna jednoznačně určená stránka. V praxi se ale mohou vrátit i více shody (širší dotaz nebo nedokonalá metadata ve zdroji).

selection_required neznamená "je více výsledků". Znamená "klient musí přepnout do ručního režimu".

Doporučené chování klienta:

• Pokud ok=true a results obsahuje více položek, vyzvat uživatele ke zpřesnění vstupu a spustit nové vyhledání.
• Pokud selection_required=true, přepnout do ručního režimu.

Chybová odpověď

Endpoint vrací chybovou odpověď ve třech praktických režimech:

HTTP 300 — manuální výběr

Endpoint nalezl více kandidátů a nelze jednoznačně určit správnou stránku. Klient musí zobrazit výběr uživateli.

{
  "ok": false,
  "error_code": "selection_required",
  "selection_required": true,
  "manual_user_message": "Bylo nalezeno více odpovídajících výsledků. Vyberte prosím správnou stránku.",
  "results": [
    {
      "api_base": "https://ndk.cz/search/api/v5.0",
      "document_uuid": "uuid:...",
      "document": "...",
      "volume_nr": "...",
      "volume_years": "...",
      "issue": "...",
      "issue_type": "...",
      "issue_date": "...",
      "supplement": "...",
      "page": "...",
      "page_label": "...",
      "citation": "...",
      "page_uuid": "uuid:...",
      "volume_uuid": "uuid:...",
      "issue_uuid": "uuid:...",
      "view_url": "https://ndk.cz/uuid/uuid:...",
      "preview_url": "https://...",
      "full_preview_url": "https://..."
    }
  ]
}

HTTP 422 — chyba dohledání

Dohledání selhalo (např. neplatný vstupní kontext stránky nebo nedostupná data zdroje). Podle typu selhání může být selection_required buď false (tvrdá chyba), nebo true (API doporučuje ruční pokračování).

{
  "ok": false,
  "error": "Položka na Wikidatech neobsahuje UUID dokumentu.",
  "error_code": "missing_document_uuid",
  "selection_required": false,
  "results": [],
  "results_meta": {
    "offset": 0,
    "batch_size": 25,
    "returned_count": 0,
    "minimum_total_count": 0,
    "has_more": false
  }
}

Pole chybové odpovědi

Kódy chyb

Pole kandidátů v results (HTTP 300)

Každý kandidát obsahuje stejná pole jako úspěšná odpověď (viz tabulku výše), doplněná o:

HTTP status kódy

Omezení počtu výsledků

• Endpoint vrací maximálně prvních 25 výsledků.
• results_meta.minimum_total_count vrací minimální jistý počet nalezených položek zjištěný v aktuálním průchodu.
• Pokud existují další kandidáti, results_meta.has_more je true.
• API neposkytuje offset/cursor pro načítání dalších dávek; klient má uživatele vést k upřesnění dotazu.

CORS konfigurace

CORS je řízen pouze environment proměnnými, takže stejný endpoint lze bezpečně použít pro web, mobil i server-to-server klienty.

Poznámka: pokud zapnete credentials, nepoužívejte wildcard origin *; nastavte explicitní whitelist.

Příklad konfigurace (dev)

export CORS_MODE="blacklist"
export CORS_BLOCKED_ORIGINS="https://evil.example,*.blocked.local"
export CORS_ALLOW_CREDENTIALS="0"
export CORS_ALLOWED_HEADERS="Content-Type,Authorization"
export CORS_MAX_AGE="600"

Poznámka: v režimu blacklist je CORS otevřený pro všechny originy mimo CORS_BLOCKED_ORIGINS.

Příklad konfigurace (produkce)

export CORS_MODE="blacklist"
export CORS_BLOCKED_ORIGINS="https://evil.example,https://malicious.example,*.botnet.invalid"
export CORS_ALLOW_CREDENTIALS="0"
export KRAMERIUS_API_CORS_ALLOWED_HEADERS="Content-Type,Authorization"
export KRAMERIUS_API_CORS_EXPOSE_HEADERS="X-Request-Id"
export KRAMERIUS_API_CORS_MAX_AGE="600"

Preflight odpověď při povoleném originu vrací minimálně:

• Access-Control-Allow-Origin: * (v režimu blacklist při CORS_ALLOW_CREDENTIALS=0)
• Access-Control-Allow-Origin: <konkrétní origin> (pokud jsou zapnuté credentials)
• Access-Control-Allow-Methods: POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Access-Control-Max-Age: 600
• Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers

CORS ověření přes curl

1) Jednoduchý GET z povoleného originu

curl -i 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Origin: https://app.example.com'

2) Preflight OPTIONS

curl -i -X OPTIONS 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Origin: https://www.daelba.eu' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

3) Blokovaný origin

curl -i -X POST 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Origin: https://www.daelba.eu' \
  -H 'Content-Type: application/json' \
  -d '{}'

curl -i -X OPTIONS 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Origin: https://evil.example' \
  -H 'Access-Control-Request-Method: POST'

curl -i -X POST 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Origin: https://evil.example' \
  -H 'Content-Type: application/json' \
  -d '{"wd":"Q123456","page":"12"}'

Očekávání pro blokovaný origin: bez Access-Control-Allow-Origin, typicky HTTP 403 a JSON s error_code: cors_origin_blocked.

cURL příklady

Wikidatový lookup:

curl -X POST 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Content-Type: application/json' \
  -d '{
    "wd": "Q96613911",
    "page": "140",
    "volume": "3",
    "volume_years": "",
    "issue": "18",
    "issue_type": "",
    "issue_date": "1849-04-01",
    "supplement": "",
    "debug": false
  }'

Přímý UUID lookup:

curl -X POST 'https://tools.daelba.eu/kramerius/api/' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuid": "35d64c24-9cf2-408b-9147-935f1323be20",
    "debug": false
  }'

Testování

Integrační test endpointu (s mockovanými externími HTTP odpověďmi):

php kramerius/tests/api-endpoint-integration-test.php

Smoke test CORS (lokální PHP server + curl):

bash kramerius/tests/cors-smoke-test.sh

Poznámka: test využívá pouze pro testovací běh environment proměnnou KRAMERIUS_HTTP_MOCK_BOOTSTRAP, která přesměruje HTTP volání na lokální mock provider.