Skip to content

Informace o titulu

Jump to bottom Edit New page
petrpodsed edited this page Aug 27, 2024 · 43 revisions

API umožňuje získávat potřebné informace o titulu důležité pro zobrazení.

Vyhledávání
Dotazy na obecné informace
Dotazy na metadata
Dotazy na OCR data
Dotazy na obrazová data
Dotazy na audio data

Specifické pro sbírky - dotaz na seznam výstřižků

Vyhledávání

Vyhledávání pomocí SOLR

GET ~/search/api/client/v7.0/search

Vyhledávání je umožněno endpointem, který slouží jako proxy do vyhledávacího enginu SOLR. Přebírá všechny parametry, validuje je a následně posílá na vyhledávací server solr. Z odpovědi jsou filtrována data typu TEXT_OCR a je posílán zpět na klienta.

Query parametry:

Možné parametry jsou všechny, které akceptuje vyhledávací engine solr. Dokumentace je k nalezení zde Popis jednotlivých indexovaných polí je k nalezení zde.

Příklad dotazu:

GET ~/search/api/client/v7.0/search?q=model:monograph&rows=1&fl=pid+pid_paths+root.model+model+titles.search

Příklad odpovědi:

{
  "response": {
    "docs": [
      {
        "titles.search": [
          "Marná sláva: profesorské romanetto"
        ],
        "pid_paths": [
          "uuid:33244df3-e448-4a2c-b69f-3a0fb96fc8c7"
        ],
        "root.model": "monograph",
        "model": "monograph",
        "pid": "uuid:33244df3-e448-4a2c-b69f-3a0fb96fc8c7"
      }
    ],
    "numFound": 2,
    "start": 0,
    "numFoundExact": true
  },
  "responseHeader": {
    "QTime": 0,
    "params": {
      "q": "model:monograph",
      "fl": "pid pid_paths root.model model titles.search",
      "hl.fragsize": "20",
      "rows": "1",
      "wt": "json"
    },
    "status": 0
  }
}

Návratové kódy: 200

sequenceDiagram
    participant Uživatel
    participant Search Endpoint
    participant Solr Engine
    
    Uživatel->>Search Endpoint: 1. Poslání požadavku
    Search Endpoint->>Search Endpoint: 2. Validace parametrů
    Search Endpoint->>Solr Engine: 3. Poslání požadavku
    Solr Engine-->>Search Endpoint: 4. Odpověď
    Search Endpoint->>Search Endpoint: 5. Ořezání chráněných dat
    Search Endpoint-->>Uživatel: 6. Odeslání odpovědi
Loading

Dotazy na obecné informace

Existence dokumentu

 HEAD  ~/search/api/client/v7.0/items/{pid}

Dotaz na existenci objektu v interním repozitáři Akubra.

Parametr Význam Povinný
pid PID dotazovaného objektu ✅

Návratové kódy: 200, 400, 403, 404

Informace o objektu pro zobrazení

 GET  ~/search/api/client/v7.0/items/{pid}/info

Vrací veškeré informace o objektu potřebné pro zobrazení.

Parametry dotazu:

Parametr Význam Povinný
pid PID dotazovaného objektu ✅

Odpověď může vypadat následovně:

{
    "image": {
        "type": "tiles"
    },
    "providedByLicenses": [],
    "data": {
        "image": {
            "preview": true,
            "thumb": true,
            "full": true
        },
        "metadata": {
            "mods": true,
            "dc": true
        },
        "audio": {
            "mp3": false,
            "wav": false,
            "ogg": false
        },
        "ocr": {
            "text": true,
            "alto": true
        }
    },
    "accessibleLocks": []
}

Popis jednotlivých klíčů v odpovědi:

Klíč Datový typ Popis
image Objekt Obsahuje informace o obrazu.
image.type Řetězec Typ obrázku. Možné hodnoty tiles, image/jp2, image/jpeg.
providedByLicenses Pole Pole. Obsahuje seznam licencí, které dle kterých se dílo poskytuje pro právě přihlášeného uživatele. (Identifikováneho pomocí Access tokenu)
data Objekt Informace o dostupnosti dat, obrázků, ocr, alta, audio souborů atd..
data.image.preview Boolean Indikuje, zda je k dispozici střední náhled obrázku (true/false).
data.image.thumb Boolean Indikuje, zda je k dispozici miniatura obrázku (true/false).
data.image.full Boolean Indikuje, zda je k dispozici obrázek v plné velikosti (true/false).
data.metadata.mods Boolean Indikuje, zda jsou dostupná metadata ve formátu BIBLIO_MODS (true/false).
data.metadata.dc Boolean Indikuje, zda jsou dostupná metadata ve formátu Dublin core (true/false).
data.metadata.dc Boolean Indikuje, zda jsou dostupná metadata ve formátu DC (true/false).
data.audio.mp3 Boolean Indikuje, zda je k dispozici audio ve formátu MP3 (true/false).
data.audio.wav Boolean Indikuje, zda je k dispozici audio ve formátu WAV (true/false).
data.audio.ogg Boolean Indikuje, zda je k dispozici audio ve formátu OGG (true/false).
data.ocr.text Boolean Indikuje, zda je k dispozici OCR výstup ve formátu text (true/false).
data.ocr.alto Boolean Indikuje, zda je k dispozici OCR výstup ve formátu ALTO (true/false).
accessibleLocks Pole Pole indikuje dostupné zámky. Vyplňuje se v případě, že je objekt chráněn licencí a zámkem. TODO: Odkaz na licence

Na jednotlivé části se lze dotazovat samostatně. Viz:

 GET  ~/search/api/client/v7.0/items/{pid}/info/data
 GET  ~/search/api/client/v7.0/items/{pid}/info/providedByLicenses
 GET  ~/search/api/client/v7.0/items/{pid}/info/image

Pokud je dílo chráněno exkluzivním zámkem a přihlášený uživatel má možnost konzumovat takovou licenci, pak v odpovědi v klíči accessibleLocks objeví možnosti získat takový zámek. Příklad takové odpovědi:

{
    "image": {
        "type": "none"
    },
    "providedByLicenses": [],
    "data": {
        "image": {
            "preview": false,
            "thumb": false,
            "full": false
        },
        "metadata": {
            "mods": true,
            "dc": true
        },
        "audio": {
            "mp3": false,
            "wav": false,
            "ogg": false
        },
        "ocr": {
            "text": false,
            "alto": false
        }
    },
    "accessibleLocks": [
        {
            "right": {
                "license": "inovatika_licence_zamek",
                "id": 50
            },
            "type": "RULE",
            "hash": "c773508668f435cb8dec9f5448d0ea78"
        }
    ]
}

Návratové kódy: 200, 400, 403, 404

Informace o struktuře

 GET  ~/search/api/client/v7.0/items/{pid}/info/structure

Vrací informace o struktuře objektu tak, jak je uložený v Akubra a processing indexu.

Příklad odpovědi:

{
  "children": {
    "own": [
      {
        "pid": "uuid:e2de5fb1-2941-44a7-977a-748926b65600",
        "relation": "hasItem"
      },
      {
        "pid": "uuid:e5e6a777-1de9-4494-9369-6acedd6e7986",
        "relation": "hasItem"
      },
      {
        "pid": "uuid:e3cced1d-71f4-44fb-87f3-dd4d612fbfb3",
        "relation": "hasItem"
      },
      {
        "pid": "uuid:f378fe14-0286-4d82-9661-e54009944f72",
        "relation": "hasItem"
      },
      {
        "pid": "uuid:d1540f99-b628-4747-a842-d0b95c0b9972",
        "relation": "hasItem"
      },
     ....
    ],
    "foster": []
  },
  "model": "periodicalvolume",
  "parents": {
    "own": {
      "pid": "uuid:06011240-a943-4efe-9f89-6707453b5f3d",
      "relation": "hasVolume"
    },
    "foster": [
      {
        "pid": "uuid:bcc986fc-7ec8-47eb-b585-121e48f7bd02",
        "relation": "contains"
      }
    ]
  }
}

Popis jednotlivých klíčů v odpovědi:

Klíč Datový typ Popis
children Objekt Obsahuje informace o potomcích objektu.
children.own Pole Seznam vlastních potomků objektu s jejich pid a relation.
children.own[].pid Řetězec Jedinečný identifikátor potomka (PID).
children.own[].relation Řetězec Typ vztahu k potomkovi
children.foster Pole Pole nevlastních potomků.
model Řetězec Typ modelu "monograph", "periodical", atd..
parents Objekt Obsahuje informace o rodičích objektu.
parents.own Objekt Informace o vlastním rodiči objektu s jeho pid a relation.
parents.own.pid Řetězec Jedinečný identifikátor rodiče (PID).
parents.own.relation Řetězec Typ vztahu k rodiči.
parents.foster Pole Seznam nevlastních rodičů objektu s jejich pid a relation. Sbírky,články, atd...
parents.foster[].pid Řetězec Jedinečný identifikátor nevlastního rodiče (PID).
parents.foster[].relation Řetězec Typ relace .

Návratové kódy: 200, 400, 403, 404

Dotazy na metadata

Existence metadat

 HEAD  ~/search/api/client/v7.0/items/{pid}/metadata/{format}

Parametry dotazu:

Parametr Význam Povinný
pid PID dotazovaného objektu ✅
format Dotazovaný formát, možné hodnoty jsou mods, dc ✅

Návratové kódy: 200, 400, 403, 404

Získání metadat

 GET  ~/search/api/client/v7.0/items/{pid}/metadata/{format}

Parametry dotazu:

Parametr Význam Povinný
pid PID dotazovaného objektu ✅
format Dotazovaný formát, možné hodnoty jsou mods, dc ✅

Vrací metadata ve formátu BIBLIO_MODS, případně ve formátu DC

Návratové kódy: 200, 400, 403, 404

Dotazy na OCR data

Existence OCR

 HEAD  ~/search/api/client/v7.0/items/{pid}/ocr/{type}

Parametry dotazu:

Parametr Význam Povinný
pid PID dotazovaného objektu ✅
type Typ ocr. Možné hodnoty text, alto ✅

Návratové kódy: 200, 400, 403, 404

Získání OCR dat

 GET  ~/search/api/client/v7.0/items/{pid}/ocr/{type}
Parametr Význam Povinný
pid PID dotazovaného objektu ✅
type Typ ocr. Možné hodnoty text, alto ✅

Vrací TEXT OCR případně ALTO.

Návratové kódy: 200, 400, 403, 404

Dotazy na obrazová data

Existence plného obrazu, IMG_FULL

 HEAD  ~/search/api/client/v7.0/items/{pid}/image
Návratové kódy: 200, 400, 403, 404

Získání plného obrazu, IMG_FULL

 GET  ~/search/api/client/v7.0/items/{pid}/image
Parametr Význam Povinný
pid PID dotazovaného objektu ✅

Získání plného obrazu z datového streamu IMG_FULL. V případě, že data jsou ve formátu JPEG 2000 případně DJVU dochází ke konverzi na typ image/jpeg

Návratové kódy: 200, 400, 403, 404

Získání náhledů

 GET  ~/search/api/client/v7.0/items/{pid}/image/{type}
Parametr Význam Povinný
pid PID dotazovaného objektu ✅
type Typ náhledu. Možné hodnoty preview (pro stream IMG_PREVIEW) nebo thumb (pro stream IMG_THUMB) ✅

Získání náhledu středního IMG_PREVIEW a malého IMG_THUMB.

Návratové kódy: 200, 400, 403, 404

Dotazy na audio data

Dotaz na existenci audiostreamu

 HEAD  ~/search/api/client/v7.0/items/{pid}/audio/{type}
Parametr Význam Povinný
pid PID dotazovaného objektu ✅
type Typ audiostreamu. Možné hodnoty mp3,ogg, wav ✅

Návratové kódy: 200, 400, 403, 404

Získání audiostreamu

 GET ~/search/api/client/v7.0/items/{pid}/audio/{type}

U audio streamu lze získat rozsah dat pomocí hlavičky Range, viz https://www.rfc-editor.org/rfc/rfc9110.html#name-range-requests

Parametr Význam Povinný
pid PID dotazovaného objektu ✅
type Typ audiostreamu. Možné hodnoty mp3,ogg, wav ✅

Návratové kódy: 200, 400, 403, 404

Endpointy přítomné v případě specifického modelu

Sbírky, získání výstřižků

 GET ~/search/api/client/v7.0/items/{pid}/collection/cuttings
Parametr Význam Povinný
pid PID dotazovaného objektu/sbírky ✅

Příklad odpovědi:

[
  {
    "thumb": "IMG_0514EF172485DC7BFD7E975B02B7FC21",
    "name": "Zar",
    "description": "Zar",
    "url": "https://k7.inovatika.dev/uuid/uuid:48f84987-3921-11ef-a7a7-001b63bd97ba?bb=659,179,2467,1143"
  },
  {
    "thumb": "IMG_DC6159E55D315F81A3D9FF89C9B8A6A6",
    "name": "Pardubice",
    "description": "Pardubice",
    "url": "https://k7.inovatika.dev/uuid/uuid:48f8709e-3921-11ef-a7a7-001b63bd97ba?bb=509,172,3050,2283"
  }
]

Viz https://github.com/ceskaexpedice/kramerius-admin-client/wiki/Administrace-p%C5%99ehled#v%C3%BDst%C5%99i%C5%BEky

Význam jednotlivých klíčů v odpovědi:

Klíč Datový typ Popis
thumb Řetězec Název datového streamu, kde je generovaný náhled
name Řetězec Název výstřižku
description Řetězec Pppisek
url Řetězec Url k generovanému náhledu

Návratové kódy: 200, 400, 403, 404

Add a custom footer
Clone this wiki locally