diff --git a/.gitignore b/.gitignore index ba1a757..c55d1c9 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ _site/ /.luarc.json + +/api.bak/ diff --git a/api/figs/api-datestamps.png b/api/figs/api-datestamps.png deleted file mode 100644 index a82796e..0000000 Binary files a/api/figs/api-datestamps.png and /dev/null differ diff --git a/api/figs/api-pristupnost.png b/api/figs/api-pristupnost.png deleted file mode 100644 index a77b510..0000000 Binary files a/api/figs/api-pristupnost.png and /dev/null differ diff --git a/api/figs/api-reseni.png b/api/figs/api-reseni.png deleted file mode 100644 index d92f80d..0000000 Binary files a/api/figs/api-reseni.png and /dev/null differ diff --git a/api/figs/api-schema.png b/api/figs/api-schema.png deleted file mode 100644 index 611c26a..0000000 Binary files a/api/figs/api-schema.png and /dev/null differ diff --git a/api/figs/api-sety.png b/api/figs/api-sety.png deleted file mode 100644 index e964da9..0000000 Binary files a/api/figs/api-sety.png and /dev/null differ diff --git a/api/figs/api_liseh.pdf b/api/figs/api_liseh.pdf deleted file mode 100644 index 7793c6b..0000000 Binary files a/api/figs/api_liseh.pdf and /dev/null differ diff --git a/api/figs/api_liseh.png b/api/figs/api_liseh.png deleted file mode 100644 index d723abb..0000000 Binary files a/api/figs/api_liseh.png and /dev/null differ diff --git a/api/index.qmd b/api/index.qmd deleted file mode 100644 index af4421d..0000000 --- a/api/index.qmd +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: "AMČR API" -subtitle: "Uživatelská příručka" -date: 2020-06-01 ---- - -::: {.callout-important} - -## Upozornění - -Následující stránka k 1. srpnu 2024 neprošla revizí a informace, které obsahuje, nemusí být plně platné pro aktuálně spuštěné verze nástrojů AMČR. -Zároveň mohou být některé odkazy, které stránka obsahuje nefunkční, screenshoty ze zastaralých verzí nástrojů apod. - -::: - -API v současné době nabízí službu *AMCR Data Provider*, která poskytuje metadatové záznamy z databáze AMČR, a to pomocí protokolu *OpenArchives Initiative Protocol for Metadata Harvesting* ([OAI-PMH](http://www.openarchives.org/pmh/){.external}). - -Naše implementace protokolu OAI-PMH podporuje - reprezentaci metadat ve standardech: - -- [Dublin Core](http://dublincore.org/){.external} -- poskytuje část datasetu týkající se dokumentů a jejich popisu; -- [~~CIDOC-CRM~~](http://www.cidoc-crm.org/){.external} -- nabízí archivovaná, volně přístupná data z AMČR ve formátu RDF v syntaxi odpovídající této ontologii; -- **AMČR XML** -- nativní formát, který umožňuje plné vytěžování databáze při zohlednění přístupových práv. - -[Uživatelé](role.qmd) s vyšším oprávněním mohou využít své přihlašovací údaje do AMČR pro přístup k nearchivovaným či jinak chráněným záznamům. -Aktualizace dat probíhá na denní bázi. - -API najdete na adrese [https://api.aiscr.cz](https://api.aiscr.cz){.external}. - -[![Poster prezentující API s příklady možných requestů [@pajdla2021a]](figs/api_liseh.png){width=60% fig-align="center" #fig-api-poster}](https://gams.uni-graz.at/o:liseh.8112/PDF_STREAM) - -## Technické řešení - -![OAI-PMH API a služba AMCR Data Provider](figs/api-schema.png){#fig-api width=80% align="center"} - -Architektura API se skládá z 5 komponent: *AMCR Filter*, *RDF Converter*, *Scrub*, *AMCR Pass* a *AMCR Data Provider*. -Všechny komponenty jsou napsány v jazyce Java. -~~Řešení používá open-source projekt X3ML Engine pro konverzi XML na RDF.~~ - -![Schéma celkového řešení API](figs/api-reseni.png){#fig-api-reseni} - -![Schéma databáze s dílčími datovými sety](figs/api-sety.png){#fig-api-sety} - -### Řešení filtrace - -#### Stav a přístupnost záznamu - -Přístupnost záznam je ovlivněna jak [procesními stavy](procesy.qmd) daných metadatových záznamů, tak [uživatelskou rolí](role.qmd). - -![Schéma přístupnosti záznamů dle uživatelských rolí](figs/api-pristupnost.png){#fig-api-pristupnost} - -#### Sety - -Selektivní výběr je umožněn pomocí nadefinovaných setů, viz také @fig-api-sety. - -```{r} -#| label: tbl-api-sets -#| tbl-cap: "Sety" - -read.csv("tabs/api-sety.csv") |> - knitr::kable() -``` - -#### Datestamps - -Pro dotazy `ListRecords` a `ListIdentifiers` je umožněno filtrování na základě volitelného argumentu -`datestamp` (from – od, until – do), kdy `datestamp` je vždy nejmladší z dostupných datumů. - -![Specifikace nastavení `datestamp` pro jednotlivé záznamy](figs/api-datestamps.png){#fig-api-datestamps} - -AMČR nepodporuje evidenci smazaných záznamů. -Po smazání záznamu z databáze proto dojde k odstranění záznamu z API bez náhrady ve formě hlavičky smazaného záznamu (`status="deleted"`). -Některé operace se v AMČR se nemusí projevit změnou `datestamp` v API. -Důvodem je způsob logování změn, který se váže pouze na specifické operace (změna [stavu](procesy.qmd) záznamu). -Při využití API proto doporučujeme data pravidelně obnovovat, nebo umožnit uživateli vynucenou aktualizaci konkrétního záznamu. -Podpora úplného sledování změn bude implementována v budoucích verzích API po provedení nutných úprav v databázi AMČR - -## Přihlášení - -Pokud chcete pro stahování dat používat svůj účet AMČR, je nutné přihlášení pomocí Basic access authentication. -Protokol https zajišťuje bezpečnou komunikaci. -Způsob přihlášení se liší v každém nástroji, který je pro stahování dat používán. -Níže jsou detailněji popsány způsoby přihlášení pro *cURL* a *Postman*. - -### cURL - -cURL je nástroj skládající se ze softwarové knihovny (libcurl) a z nástroje příkazového řádku (curl) sloužících ke stahování souborů přes počítačovou síť. -Nástroj je dostupný pro různé operační systémy Linux, macOS a Windows. -Své uživatelské jméno a heslo je možné zadat pomocí přepínače -u. - -``` -curl -u username:password -``` - -Přihlašovací údaje je nutné posílat v každém requestu. - -### Postman - -Postman je multiplatformní aplikace pro vývojáře sloužící k návrhu a interakci s HTTP API. -Uživatelské jméno a heslo lze zadávat na kartě *Autorizace*. -V rozevírací nabídce *TYPE* zvolte možnost *Basic Auth* a stiskněte tlačítko *Odeslat*. -Přihlašovací údaje jsou poté posílány automaticky v každém requestu. - -## Verbs - -Dotazování v protokolu OAI-PMH je možné pomocí tzv. sloves (verbs). -Význam jednotlivých sloves s příkladem užití jsou popsány v následujících kapitolách. -Podrobná specifikace protokolu OAI-PMH je k dispozici [zde](http://www.openarchives.org/OAI/openarchivesprotocol.html){.external}. - -### Identify - -Sloveso `Identify` se používá k získání informací o úložišti. - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=Identify](https://api.aiscr.cz/dapro/oai?verb=Identify){.external} - -### ListMetadataFormats - -Sloveso `ListMetadataFormats` se používá k načtení formátů metadat dostupných z úložiště. - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListMetadataFormats](https://api.aiscr.cz/dapro/oai?verb=ListMetadataFormats){.external} - -Odpověď: - -::: {.small} - -```xml - - 2023-07-10T14:10:00Z - https://api.aiscr.cz/dapro/oai - - - oai_dc - http://www.openarchives.org/OAI/2.0/oai_dc.xsd - http://www.openarchives.org/OAI/2.0/oai_dc/ - - - oai_rdf - https://api.aiscr.cz/dapro/media/oai_rdf.xsd - https://api.aiscr.cz/schema/oai_rdf/ - - - oai_amcr - https://api.aiscr.cz/dapro/media/oai_amcr.xsd - https://api.aiscr.cz/schema/oai_amcr/ - - - -``` - -::: - -Implementace OAI-PMH podporuje reprezentaci metadat v: - -- Dublin Core – `metadataPrefix` `oai_dc`, -- ~~CIDOC-CRM – `metadataPrefix` `oai_rdf`,~~ -- interním AMČR XML – `metadataPrefix` `oai_amcr`. - -Jednotlivá schémata jsou k dispozici na: https://api.aiscr.cz/dapro/media/*.xsd. - -### ListIdentifiers - -Sloveso `ListIdentifiers` se používá pro načtení záhlaví záznamů (header) z úložiště. -Povinným argumentem je `metadataPrefix`. -Nepovinné argumenty umožňují filtraci záhlaví na základě nastavených [setů](api.qmd#sety) a/nebo [datestamp](api.qmd#datestamps). -Uživatel dostane v odpovědi první stránku se záhlavím záznamů. -Pro načtení dalších stránek je nutné použit [`resumptionToken`](api.qmd#resumptionToken). - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&metadataPrefix=oai_amcr](https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&metadataPrefix=oai_amcr){.external} - -### ListRecords - -Sloveso `ListRecords` se používá pro načtení záznamů z úložiště. -Povinným argumentem je `metadataPrefix`. -Nepovinné argumenty umožňují filtraci záznamů na základě nastavených [setů](api.qmd#sety) a/nebo [datestamp](api.qmd#datestamps). -Uživatel dostane v odpovědi první stránku se záznamy. -Pro načtení dalších stránek je nutné použit [`resumptionToken`](api.qmd#resumptionToken). - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListRecords&metadataPrefix=oai_amcr](https://api.aiscr.cz/dapro/oai?verb=ListRecords&metadataPrefix=oai_amcr){.external} - -Odpověď: - -::: {.small} - -```xml - - 2023-07-11T07:21:17Z - https://api.aiscr.cz/dapro/oai - - -
- https://api.aiscr.cz/id/C-201773056 - 2022-06-09 - projekt -
- - - - C-201773056 - 6 - záchranný - 2016-01-01 00:00:00 - PLZEŇ-SEVER - (...) - 2019-12-30 - C-201773056A - - - - - 2023-07-10.oai_amcr.1000.projekt.1000.1000...f - - -``` - -::: - -### GetRecord - -Sloveso `GetRecord` se používá k získání individuálního záznamu metadat z úložiště. -Požadované argumenty jsou `metadataPrefix` a identifikátor položky (`identifier`), ze které je záznam požadován. -Položky jednotlivých setů nesou v hlavičce persistentní identifikátory, odvozované z pole *ident_cely* u jednotlivých záznamů nejvýše v XML struktuře záznamu v daném setu. -Výjimkou je set soubor, kde jako identifikátor slouží pole `filepath`. -K základnímu formátu identifikátoru je vždy jako prefix připojena URL: `https://api.aiscr.cz/id/`. -Odkazy mezi záznamy napříč sety jsou řešeny na úrovni základního identifikátoru bez prefixu. -Další informace ke struktuře identifikátorů a vazbám naleznete v samostatné [kapitole](identifikatory.qmd). - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=GetRecord&identifier=https://api.aiscr.cz/id/C-DL-200400001&metadataPrefix=oai_amcr](https://api.aiscr.cz/dapro/oai?verb=GetRecord&identifier=https://api.aiscr.cz/id/C-DL-200400001&metadataPrefix=oai_amcr){.external} - -Odpověď: - -::: {.small} - -```xml - - 2023-07-11T07:37:18Z - https://api.aiscr.cz/dapro/oai - - -
- https://api.aiscr.cz/id/C-DL-200400001 - 2018-06-15 - dokument -
- - - - C-DL-200400001 - C-LET-00253 - (...) - - C-DL-200400001-D01 - (...) - - C-DL-200400001-K01 - C-DL-200400001-D01 - pr.zem - sídliště nesp. - 1 - 0 - (...) - - (...) - - - - - - - - - -``` - -::: - -### ListSets - -Sloveso `ListSets` se používá k načtení nastavené struktury úložiště, tzv. setů. - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListSets](https://api.aiscr.cz/dapro/oai?verb=ListSets){.external} - -## Parametry - -### Stránkování - -Pomocí sloves uživatel získává první stránku požadovaných metadat. -Pro získání dalších záznamů je nutné použit parametr `resumptionToken`, který uživatel dostal v odpovědi na svůj dotaz. -Parametr `resumptionToken` je vždy na konci odpovědi. -Počet záznamů na stránku je dán konfigurací na straně poskytovatele API. - -Odpověď na dotaz v sekci [ListRecords](api.qmd#listrecords) vrátila následující XML element obsahující `resumptionToken`, který je použit v dalším dotazu: - -```xml - - 2023-07-10.oai_amcr.1000.projekt.1000.1000...f - -``` - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&resumptionToken=2023-07-10.oai_amcr.1000.projekt.1000.1000...f](https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&resumptionToken=2023-07-10.oai_amcr.1000.projekt.1000.1000...f){.external} - -Parametr `resumptionToken` je v tomto případě společně se slovesy `ListRecords` a `ListIndentifiers` -výhradním parametrem. - -### Filtrování - -Tzv. selektivní sklizeň umožňuje uživatelům omezit požadavky na sběr dat na části metadat dostupných z úložiště. -OAI-PMH podporuje selektivní sklizeň se dvěma typy kritérií pro sklizeň, která mohou být kombinována: `datestamp` a `set`. -Data provider AMČR navíc uživatelům filtruje záznamy podle jejich přístupnosti. - -#### Podle přístupnosti záznamu - -Při zpracování dotazu jsou uživateli automaticky záznamy filtrovány podle přístupnosti, která je nadefinovaná v AMČR. -Anonymní uživatel má vždy přístupnost pouze k archivovaným záznamům. -Archeologové či uživatelé s vyšším oprávněním mají přístup i k nearchivovaným či jinak chráněným záznamům. -Vice viz kapitoly k [procesním stavům](procesy.qmd) a [uživatelským rolím](role.qmd). - -#### Pomocí Setů - -Protokol OAI-PMH umožňuje filtrování pomocí nadefinovaných setů, a to přidáním parametru `set`. -Pomocí slovesa `ListSets` je možné získat hodnotu `setSpec` pro všechny nadefinované [sety](api.qmd#sety), viz také @fig-api-sety. -Pro zvolené filtrování se poté do requestu se slovesy `ListRecords` nebo `ListIndentifiers` přidává parametr `set=setSpec`. -Filtrování pomocí setů lze kombinovat s filtrováním pomocí `datestamp`. - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListRecords&set=akce&metadataPrefix=oai_amcr](https://api.aiscr.cz/dapro/oai?verb=ListRecords&set=akce&metadataPrefix=oai_amcr){.external} - -#### Pomocí datestamp - -Protokol OAI-PMH umožňuje filtrování pomocí datumu (`datestamp`), přiřazeného ke každému záznamu. -Pro požadované filtrování se poté do requestu se slovesy `ListRecords` nebo `ListIndentifiers` přidává parametr `from` (od) a/nebo `until` (do). - -Dotaz: [https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&metadataPrefix=oai_amcr&from=2022-12-10&until=2022-12-20](https://api.aiscr.cz/dapro/oai?verb=ListIdentifiers&metadataPrefix=oai_amcr&from=2022-12-10&until=2022-12-20){.external} diff --git a/api/tabs/api-sety.csv b/api/tabs/api-sety.csv deleted file mode 100644 index c320ef8..0000000 --- a/api/tabs/api-sety.csv +++ /dev/null @@ -1,12 +0,0 @@ -setSpec, setName -projekt, Projekty / Projects -akce, Akce / Fieldwork Events -lokalita, Lokality / Sites -dok_jednotka, Dokumentační jednotky / Descriptive Units -adb, Archeologický dokumentační bod / Archaeological Documentation Point -dokument, Dokumenty / Documents -soubor, Soubory / Files -pian, PIAN / Spatial Units -ext_zdroj, Externí zdroje / External Sources -let, Lety / Flights -samostatny_nalez, Samostatné nálezy / Individual Finds \ No newline at end of file