Toto je starší verze dokumentu!
Technické standardy pro aplikační rozhraní lokálních katalogů
Aby mohl být lokální katalog registrován v NKOD, musí nabízet aplikační rozhraní (API) splňující následující specifikaci. API je webová služba obsahující funkce package_list a package_show ze specifikace CKAN API verze 3. Výstup funkce package_show je rozšířen o dodatečná metadata. Výstupy obou funkcí jsou ve formátu JSON (ECMA-404).
Obě funkce musí být přístupné na adrese lokálního katalogu pod pevně stanovenými URL.
Příklad: lokální katalog běží na adrese http://data.organizace.cz. Funkce package_list je pak přístupná na adrese http://data.organizace.cz/api/3/action/package_list a funkce package_show je pak přístupná na adrese http://data.organizace.cz/api/3/action/package_show?id=datova-sada-1 kde „datova-sada-1“ je ID konkrétní datové sady v lokálním katalogu sestávající z malých písmen bez diakritiky, čísel, podtržítek a pomlček.
package_list
Odpověď na volání funkce package_list obsahuje v poli result seznam ID všech datových sad obsažených v katalogu. Tato ID se pak použijí pro volání funkce package_show. Odpověď má tvar:
{ "success": true, "result": [ "datova-sada-1", "datova-sada-2", "datova-sada-3" ] }
package_show
Odpověď na volání funkce package_show s parametrem id obsahujícím ID datové sady obsahuje mimo jiné kompletní metadata datové sady a všech jejích distribucí. Pole result obsahuje mimo jiné následující parametry:
Název pole | Název položky | Datový typ | Povinnost | Příklad hodnoty |
---|---|---|---|---|
title | Název datové sady | Řetězec | Ano | Kontroly |
notes | Popis datové sady | Řetězec | Ano | Seznam kontrol od 1.1.2012 |
frequency | Periodicita aktualizace | Řetězec dle ISO 8601 | Ano | R/P3M |
ruian_type | Související geografické území - typ prvku RÚIAN | Typ prvku RÚIAN | Ano | ST |
ruian_code | Související geografické území - kód prvku RÚIAN | Řetězec | Ano | 1 |
theme | Klasifikace dle EuroVoc | Seznam URL oddělený mezerou | Ne | http://eurovoc.europa.eu/171 |
maintainer_email | Email Kurátora dat | Ne | verejnadata@INSTITUCE.cz | |
maintainer | Jméno Kurátora dat | Řetězec | Ne | Jan Novák |
schema | Odkaz na dokumentaci datové sady | URL | Ne | http://www.INSTITUCE.cz/open-data/dokumentace-ds1.html |
tags | Klíčová slova | pole objektů | Ano | viz níže |
temporal_start | Dotčené časové období od | datum ve formátu xsd:date | Ne | 2012-01-01 |
temporal_end | Dotčené časové období do | datum ve formátu xsd:date | Ne | 2014-12-31 |
publisher_uri | URL poskytovatele dat | URL | Ano | http://www.INSTITUCE.cz |
publisher_name | Název poskytovatele dat | Řetězec | Ano | INSTITUCE |
resources | Datové zdroje | pole objektů | Ano | viz níže |
Navíc pole result obsahuje:
- položku name obsahující ID datové sady použité jako parametr funkce package_show a zobrazené v seznamu vráceném funkcí package_list.
Příklad:
"name": "coi-kontroly"
- Pole klíčových slov, kde každé je reprezenováno objektem o dvou položkách se stejným obsahem name a display_name.
Příklad:
"tags": [{ "display_name": "kontroly", "name": "kontroly" }],
- Pole obsahující metadata jednotlivých datových zdrojů resources, viz popis distribuce.
V poli resources má každá distribuce (datový zdroj) mimo jiné následující parametry:
Název pole | Název položky | Datový typ | Povinnost | Příklad hodnoty |
---|---|---|---|---|
url | Odkaz na stažení datového zdroje | URL | Ano | http://www.INSTITUCE.cz/open-data/kontroly.trig |
format | Formát datového zdroje | MIME typ | Ano | application/trig |
license_link | Odkaz na podmínky užití | URL | Ano | https://portal.gov.cz/portal/ostatni/volny-pristup-k-ds.html |
name | Název datového zdroje | Řetězec | Ne | Kontroly |
describedBy | Odkaz na strojově čitelné schéma datového zdroje | URL | Ne | http://www.INSTITUCE.cz/open-data/ontologie.trig |
describedByType | Formát schématu datového zdroje | MIME typ | Ne | application/trig |
temporal_start | Dotčené časové období od | datum ve formátu xsd:date | Ne | 2015-01-01 |
temporal_end | Dotčené časové období do | datum ve formátu xsd:date | Ne | 2015-12-31 |
Kompletní příklad výstupu funkce package_show
Dle standardu DCAT jsou podmínky užití vlastností datového zdroje, jelikož každý datový zdroj může mít podmínky jiné. Položku license_link lze uvést i v poli datové sady result, pak se interpretuje jako že jsou podmínky užití stejné pro všechny datové zdroje.