5.2. Popis rozhraní

REST rozhraní je soubor jednotlivých služeb. Tyto služby umožňují:

  • zjišťování seznamu balíčků v digitálním archivu

  • zjišťování změn v balíčcích

  • vkládání požadavků na stažení balíčků

  • vkládání požadavků na stažení souborů (komponent) z balíčků

  • zjišťování stavu požadavků na stažení

  • stahování připravených výsledků

  • zjišťování stavu požadavků na změny balíčků

  • stahování výsledků požadovaných změn.

Pro přenos výsledků a vkládání požadavků na změny do digitálního archivu je určeno primárně navazující přenosové rozhraní.

V samostatné kapitole jsou uvedena doporučení pro implementaci.

5.2.1. OpenAPI

Podrobná definice rozhraní je popsána pomocí OpenAPI. Definice obsahuje specifikaci metod a podobu návratových JSON objektů.

Specifikace rozhraní ke stažení: openapi.yaml

POST /download/aips

Stažení balíčků v poslední verzi.

Metoda umožňuje zahájení stahování jednoho nebo více balíčků v požadované podobě. Stahování balíčků je asynchronní a nejprve je nutné vložit tento požadavek na stažení.

Příprava dat pro stažení může trvat delší dobu a stav přípravy dat je možné zjistit pomocí metody batchStatus. Připravenou dávku lze následně stáhnout a to buď pomocí přímého volání nebo obzvlášť v případě většího objemu dat pomocí FileTransfer.

Výsledkem volání je identifikátor dávky, která bude na serveru připravena. Dávka je tvořena vždy sadou adresářů pojmenovaných shodně jako je identifikátor daného balíčku. V adresáři jsou umístěny soubory vztahující se k danému balíčku.

Status Codes:

  • 200 OK – Vrací identifikátor dávky ke stažení. Výslednou dávku je možné přenést službou FileTransfer.

  • 403 Forbidden – Chyba stažení balíčku způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

  • 404 Not Found – Chyba způsobená uvedením neplatné hodnoty parametru, obvykle chybným uvedením identifikátoru balíčku nebo požadovaným typem balíčku. V detailním popisu chyby jsou uvedeny další podrobnosti.

POST /download/files

Stažení jednoho nebo více souborů z balíčku.

Metoda připraví dávkové stažení jednoho nebo více souborů z jednoho AIPu. Stahování souborů je asynchronní a nejprve je nutné vložit tento požadavek na jejich stažení.

Příprava dat pro stažení může trvat delší dobu a stav přípravy dat je možné zjistit pomocí metody batchStatus. Připravenou dávku lze následně stáhnout a to buď pomocí přímého volání nebo obzvlášť v případě většího objemu dat pomocí FileTransfer.

Výsledkem volání je identifikátor dávky, která bude na serveru připravena.

Status Codes:

  • 200 OK – Vrací identifikátor dávky ke stažení. Výslednou dávku je možné přenést službou FileTransfer.

  • 403 Forbidden – Chyba stažení balíčku způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

  • 404 Not Found – Chyba způsobená uvedením neplatné hodnoty parametru, obvykle chybným uvedením identifikátoru balíčku nebo požadovaným typem balíčku. V detailním popisu chyby jsou uvedeny další podrobnosti.

GET /download/result/{batchId}

Stažení připravené dávky.

Metoda slouží pro stažení připravené dávky. Dávku je možné stahovat až když metoda getStaus vrátí, že je dávka dokončena (stav FINISHED).

V případě velkého objemu dat nebo i z jiných implementačních důvodů může být nutné výsledek stáhnout pomocí služby FileTransfer a nikoliv pomocí této metody. Tento stav je signalizován návratovým kódem 413.

Parameters:

  • batchId (string) – Identifikátor dávky, která bude stažena

Status Codes:

  • 200 OK – Dojde k zahájení stahování výsledku. Ten je předán ve formě ZIP souboru v němž jsou uloženy jednotlivé soubory výsledku.

  • 403 Forbidden – Chyba stažení balíčku způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

  • 404 Not Found – Chyba způsobená uvedením neplatné hodnoty parametru, obvykle chybným uvedením identifikátoru balíčku nebo požadovaným typem balíčku. V detailním popisu chyby jsou uvedeny další podrobnosti.

  • 413 Request Entity Too Large –

    Chyba způsobená příliš velkým datovým objemem odpovědi.

    K chybě může dojít při požadavku na přímé stažení balíčku nebo souboru. Pro získání požadovaných dat musí být v takovém případu využito dávkové API, které umožňuje přenos větších objemů dat a navazování přeušeného stahování.

GET /download/status/{batchId}

Zjištění stavu zpracování dávky.

Metoda umožňuje po vložení požadavku, který vrací BatchId, zjistit stav zpracování dávky. Dle stavu lze následně provést stažení výsledku.

Parameters:

  • batchId (string) – Identifikátor dávky jejíž stav je zjišťován

Status Codes:

  • 200 OK – Vrací informaci o stavu zpracování dávky. Připravený výsledek je možné stáhnout pomocí služby FileTransfer. V případě vrácení chybových stavů 403 a 404 se jedná o trvalé selhání požadavku a jeho příprava je již přerušena.

  • 403 Forbidden – Chyba stažení balíčku způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

  • 404 Not Found – Chyba způsobená uvedením neplatné hodnoty parametru, obvykle chybným uvedením identifikátoru balíčku nebo požadovaným typem balíčku. V detailním popisu chyby jsou uvedeny další podrobnosti.

GET /ingest/result/{batchId}

Převzetí výsledku zpracování dávky

Metoda slouží pro převzetí výsledku zpracování dávky balíčků. Výsledek je možné převzít až když metoda getStaus vrátí, že je dávka dokončena (stav FINISHED).

Parameters:

  • batchId (string) – Identifikátor dávky pro převzetí výsledku

Status Codes:

  • 200 OK – Výsledek zpracování jednotlivých předaných balíčků.

  • 403 Forbidden –

    Chyba vložení způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

    V případě této chyby nedošlo ke zpracování žádné části z vkládané dávky.

  • 404 Not Found –

    Chyba způsobená uvedením neplatné podoby vstupní dávky. V detailním popisu chyby jsou uvedeny další podrobnosti.

    V případě této chyby nedošlo ke zpracování žádné části z vkládané dávky.

  • 503 Service Unavailable –

    Výsledek zpracování dávky není dostupný.

    K chybě může dojít v případě předčasného volání metody getResult. Metoda by měla být volána až po dokončení zpracování vstupní dávky indikovaném pomocí metody getStatus.

GET /ingest/status/{batchId}

Zjištění stavu zpracování požadavku na aktualizaci balíčků.

Metoda umožňuje po vložení změnových balíčků zjistit stav jejich zpracování. Podle zjištěného stavu lze následně provést stažení výsledku.

Parameters:

  • batchId (string) – Identifikátor dávky jejíž stav je zjišťován.

Status Codes:

  • 200 OK – Vrací informaci o stavu zpracování dávky. Připravený výsledek je možné stáhnout pomocí metody getResult. V případě vrácení chybových stavů 403 a 404 se jedná o trvalé selhání požadavku a jeho další zpracování je přerušeno.

  • 403 Forbidden –

    Chyba vložení způsobená nedostatečným oprávněním. Případné upřesnění chybějícího oprávnění je uvedeno chybovém objektu.

    V případě této chyby nedošlo ke zpracování žádné části z vkládané dávky.

  • 404 Not Found –

    Chyba způsobená uvedením neplatné podoby vstupní dávky. V detailním popisu chyby jsou uvedeny další podrobnosti.

    V případě této chyby nedošlo ke zpracování žádné části z vkládané dávky.

GET /updates

Zjištění seznamu dostupných balíčků a jejich změn v digitálním archivu.

Metoda umožňuje získat úplný seznam balíčků v digitálním archivu dostupných pro uživatele a sledovat změny v těchto balíčcích.

Povinným parametrem je maximální počet záznamů vrácených v odpovědi. Volitelným parametrem je identifikátor pro zjištění dalších balíčků a jejich změn.

Query Parameters:

  • nextQuery (string) – Volitelný identifikátor dalšího dotazu. Jeho hodnota je vrácena jako výsledek předcházejícícho dotazu. Při prvním dotazu se parametr neuvádí.

  • pageSize (integer) – Maximální počet vrácených záznamů. (Required)

Status Codes:

  • 200 OK – Vrací seznam dostupných balíčků. Počet vrácených balíčků je nanejvýš počet uvedený v parametru pageSize. Server může vrátit nižší počet, než-li je hodnota pageSize. Pokud nejsou žádné balíčky a jejich změny dostupné, je vrácen prázdný seznam.

  • 404 Not Found – Chyba způsobená uvedením neplatné hodnoty parametru je signalizována návratovým kódem 404 a chybovým objektem s detailním popisem.