OpenAPI verze 1.4.0

[daliboris]

• [x] proč má volání api/enrich/download-k-structure parametr override, zatímco ostatní metody pro obohacení nikoli? Vidím v tom nejednotnost ovládání aplikace.
• [ ] u exportů (/api/export/{id}/{format} a /api/export/{id}/tei) navrhuju zavést nový parametr jobName (podobně jako u /api/enrich/...), např. abych mohl odlišit různé důvody exportu (např. pro určitého uživatele nebo s určitými parametry)
• [ ] metoda /api/export/{id}/tei vytvoří úlohu typu EXPORT (tj. "krameriusJob": "EXPORT"), zatímco obdobné metody /api/export/{id}/{format} vytvoří úlohu typu EXPORTING_JOB. Je nějaký důvod rozlišovat EXPORT a EXPORTING_JOB?

[bodnarIQ]

V prvom rade by som rad upozornil na zmeny API vo verzi 1.5.0. Uvedomujem si, ze som na poslednej schodzke spominal, ze by sa rozhranie pre existujuce endpointy nemalo menit, no vzhladom na zjednodusenie uzivatelskeho pouzitia som sa rozhodol API predsa len mierne upravit. Vytiahol som spolocnu konfiguraciu do samostatneho atributu. Tato konfiguracia bude pri volani API jednotne aplikovana na vsetky publikacie v mnozine publicationIds. Dokumentacia je uz dostupna na DEV prostredi

---

proč má volání api/enrich/download-k-structure parametr override, zatímco ostatní metody pro obohacení nikoli? Vidím v tom nejednotnost ovládání aplikace.

API /api/enrich/download-k-structure ma jako jediny parametr override, pretoze ako jediny vytvara digitalne objekty (vola sa metoda INSERT do DB) a bolo tu preto nutne osetrit situaciu, pokial dany digitalny objekt uz v databazi existuje. Ostatne metody volaju v podstate stale UPDATE - vykonavaju upravu dat na existujucom digitalnom objekte, takze v podstate pracuju stale s implicitnym nastavenim override=true.

Je moznost toto chovanie rozsirit na vsetky ulohy - pred spustenim ulohy by sa kontrolovalo, ze ci existuje uspesne ukoncena uloha daneho typu pre danu publikaciu a nasledne by sa postupovalo podla nastavenia atributu override.

Zaroven by som tuto moznost tym padom presunul do konfiguracie jednotlivych uloh (vid. dokumentace pro API v1.5.0)

---

u exportů (/api/export/{id}/{format} a /api/export/{id}/tei) navrhuju zavést nový parametr jobName (podobně jako u /api/enrich/...), např. abych mohl odlišit různé důvody exportu (např. pro určitého uživatele nebo s určitými parametry)

• Preferujete pridat moznost definovat jobName pre vsetky ulohy, alebo len pre ulohy typu EXPORT ? (Nazov by bol sucastou konfiguracie ulohy. U uloh pre obohacovanie je moznost vytvorit viac uloh jednym volanim, coho dopadom by bolo, ze vsetky ulohy by tym padom zdielali rovnaky definovany nazov)
• U /api/enrich/... nie je moznost pomenovania konkretnych vytvaranych uzivatelskych uloh pokial viem, rozlisuje sa tam iba TYP uloh. EXPORT je samotny TYP ulohy, rovnako ako DOWNLOAD_K_STRUCTURE ci ENRICH_TEI.

---

metoda /api/export/{id}/tei vytvoří úlohu typu EXPORT (tj. "krameriusJob": "EXPORT"), zatímco obdobné metody /api/export/{id}/{format} vytvoří úlohu typu EXPORTING_JOB. Je nějaký důvod rozlišovat EXPORT a EXPORTING_JOB?

Obe API by mali vytvorit ulohu typu EXPORT, uloha typu EXPORTING_JOB aktualne uz neexistuje (bola premenovana na EXPORT). Nepodarilo sa mi toto spravanie nasimulovat.

[daliboris]

Ad úloha typu EXPORT: je pravda, že teď všechny metody vracejí úlohu typu EXPORT, takže to považuju za uzavřené. V testech kontrola vráceného typu úlohy zůstává.

[daliboris]

Při volání metody /api/export/{id}/{format} s nevalidním parametrem format, např. s hodnotou xml, vrací server chybu 500. (Např. /api/export/uuid:0c94cf70-188a-11e4-8f64-005056827e52/xml).

Odpověď by měla vracet kód 400.

[daliboris]

Stále platí moje připomínka, že by pojmenování koncových bodů měla odpovídat doporučením, tj. označení kolekcí by mělo být v množném čísle, tj. exports, publications, jobs, a dokonce i infos viz LIBCAS/DL4DH-Kramerius-plus#38.

Koncové body /enrich/ bych přejmenoval na enrichment, protože enrich je sloveso a v OpenAPI by se slovesa měla vyskytovat v označeních metod, tj. POST, GET ap.

A když už jsme u obohacování, změnil/zjednodušil bych pojmenování ještě víc, konkrétně:

• enrich/enrich-tei >> enrichment/tei
• enrich/enrich-ndk >> enrichment/ndk
• enrich/enrich-external >> enrichment/external
• enrich/download-k-structure >> enrichment/kramerius

Dávám ke zvážení, že by se podobným způsobem mohly přejmenovat i typu úloh, tj. ENRICH_TEI >> ENRICHMENT_TEI

[daliboris]

Je moznost toto chovanie rozsirit na vsetky ulohy - pred spustenim ulohy by sa kontrolovalo, ze ci existuje uspesne ukoncena uloha daneho typu pre danu publikaciu a nasledne by sa postupovalo podla nastavenia atributu override.

Takto nějak jsem si to představoval: pokud úloha stejného typu proběhla, bylo by zbytečné volat služby znova a zatěžovat různé servery.

Někdy ale bude potřeba úlohu spustit znovu, a to v těchto případech:

• změnily se parametry úlohy
• změnila se implementace externí služby (např. nová verze NameTagu ap.)
• změnila se implementace aplikace, která úlohy spouští (např. došlo k rozpoznání objektu typu supplement)

[daliboris]

Ostatne metody volaju v podstate stale UPDATE

Podle doporučení (zde nebo zde) se pro aktualizaci dat používá metoda PUT nebo PATCH

[bodnarIQ]

Stále platí moje připomínka, že by pojmenování koncových bodů měla odpovídat doporučením, tj. označení kolekcí by mělo být v množném čísle, tj. exports, publications, jobs, a dokonce i infos viz LIBCAS/DL4DH-Kramerius-plus#38.

Koncové body /enrich/ bych přejmenoval na enrichment, protože enrich je sloveso a v OpenAPI by se slovesa měla vyskytovat v označeních metod, tj. POST, GET ap.

A když už jsme u obohacování, změnil/zjednodušil bych pojmenování ještě víc, konkrétně:

• enrich/enrich-tei >> enrichment/tei
• enrich/enrich-ndk >> enrichment/ndk
• enrich/enrich-external >> enrichment/external
• enrich/download-k-structure >> enrichment/kramerius

Dávám ke zvážení, že by se podobným způsobem mohly přejmenovat i typu úloh, tj. ENRICH_TEI >> ENRICHMENT_TEI

Nazvy kolekci som opravil (info ostalo nezmenene, kedze je to od slova information, ktore je nepocitatelne - neexistuje informations)

Je moznost toto chovanie rozsirit na vsetky ulohy - pred spustenim ulohy by sa kontrolovalo, ze ci existuje uspesne ukoncena uloha daneho typu pre danu publikaciu a nasledne by sa postupovalo podla nastavenia atributu override.

Takto nějak jsem si to představoval: pokud úloha stejného typu proběhla, bylo by zbytečné volat služby znova a zatěžovat různé servery.

Někdy ale bude potřeba úlohu spustit znovu, a to v těchto případech:

• změnily se parametry úlohy
• změnila se implementace externí služby (např. nová verze NameTagu ap.)
• změnila se implementace aplikace, která úlohy spouští (např. došlo k rozpoznání objektu typu supplement)

Zacal som s implementaciou tohto validacneho kroku u vsetkych uloh pre obohacovanie. Napadlo ma ale, ci je dostatocne kontrolovat existenciu ukoncenej ulohy. Ak by sa totiz viacere ulohy rovnakeho typu pre rovnaku publikaciu pustili paralelne, ani jedna z nich by nebola v stave COMPLETED a tym padom by validacny krok presiel, no pocas obohacovania by si navzajom prepisovali data. Zaroven je teda otazne, ci umoznit spustit ulohu s override=false, pokial existuje nejaka uloha v stave FAILED (a je ju mozne restartovat, pricom sa bude pokracovat od posledneho uspesneho kroku).

Preto navrhujem upravit podmienky vo validacnom kroku. Pre umoznenie spustenia ulohy by malo platit jedno z nasledujucich podmienok:

• parameter override je nastaveny na true, nebo
• neexistuje ziadna ina uloha rovnakeho typu pre rovnaku publikaciu (v lubovolnom stave)

Ak sa obe podmienky vyhodnotia na false, uloha sa nespusti. Inymi slovami, pokial je override=false, moze byt uloha spustena iba ak sa spusta uplne poprve.

Ostatne metody volaju v podstate stale UPDATE

Podle doporučení (zde nebo zde) se pro aktualizaci dat používá metoda PUT nebo PATCH

k UPDATE dochadza iba v spojeni s objektom danej publikacie na databazovej urovni, v skutocnosti sa vytvara a spusta nova uloha, takze si myslim ze je spravne pouzitie metody POST