Zpřístupnit jednoduché JSON API

[petrbouchal]

Potřeba/popis workflow uživatele:

1. chci jednorázově stáhnout metadata k nějak definované množině datasetů (např. podle poskytovatele, klíčového slova, tématu); metadata by měla obsahovat kromě lidsky čitelného popisu (název poskytovatele, název a popis sady) i nějaký pointer směrem k distribuci.
2. poté, co se pohrabu v katalogu staženém v kroku 1 se chci v co nejmenším počtu requestů dostat od záznamu v sadě popsané výše distribuci (napadá mě varianta např. přímo v metadatech k datasetu zveřejnit URL nejnovější distribuce).

Alternativně u 1 může být vyhledávání v některých polích spíš než stažení sady podle atributů, ale to není velký rozdíl.

V podstatě to může vypadat podobně jako API, ze kterého tahá data současný web front end NKOD. Jen by to mělo být zdokumenované, stabilní a o možná o malinko jednodušší (viz např. bod 2 výše).

Ideálně upřednostnit obsloužení typického discovery <> use workflow před ontologickou úplností; dokumentaci raději ve slovech než v kompletních URI atd.

[jakubklimek]

K tomuto účelu slouží SPARQL endpoint https://data.gov.cz/sparql (se SPARQLem si lze hrát i ve více user-friendly editoru), ve kterém jsou všechna metadata NKOD dle specifikace standardu DCAT a DCAT-AP 1.2.1, a kde je možné se libovolně databázově dotázat (RESTovsky). Strukturu dat lze také procházet pomocí rozkliknutí šipky z názvu datasetu.

Tedy popsaný scénář lze splnit 2 requesty - jedním dostanu vyfiltrovaný seznam, druhým odkazy ke stažení. Navíc je obsah NKOD poskytován i jako CSV, HDT a RDF TriG dump pro použití v jiné instanci databáze.

API, přes které tahá web frontentu, není stabilní, jelikož se bude vyvíjet s každým updatem NKOD (aktuálně naplánováno 2x ročně). Datová struktura se bude vyvíjet také, ale standard DCAT se zatím vyvíjí více méně přidáváním položek, čili zpětně kompatibilně.

Tedy například

PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX dcat: <http://www.w3.org/ns/dcat#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?dataset ?název ?poskytovatel WHERE {
  GRAPH ?g {
    ?dataset a dcat:Dataset ;
        dcterms:title ?název ;
      	dcterms:publisher ?publisher .
    
    ?publisher foaf:name ?poskytovatel .
    
    VALUES ?publisher {
      <https://data.gov.cz/zdroj/ovm/00075370> # IRI pro Plzeň
    }
    FILTER(lang(?poskytovatel) = "cs")
    FILTER(lang(?název) = "cs")
  }
}

vrátí seznam datasetů (formát se dá nastavit - HTML, CSV, ...), která se dají použít ve VALUES kroku 2:

PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX dcat: <http://www.w3.org/ns/dcat#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?url WHERE {
  GRAPH ?g {
    ?dataset a dcat:Dataset ;
        dcat:distribution ?distribution .
    
    ?distribution dcat:downloadURL ?url .
    
    VALUES ?dataset {
      <https://data.gov.cz/zdroj/datové-sady/https---opendata.plzen.eu-api-3-action-package_show-id-gis-ostatni-wc> # IRI pro dataset
    }
  }
}

který vrátí seznam URL distribucí.

zveřejnit URL nejnovější distribuce

Všechny distribuce jedné datové sady jsou stejně nové, a měly by mít stejný obsah lišící se pouze formátem (což tak bohužel poskytovatelé občas nedělají).

[petrbouchal]

Moc díky za odpověď a za rady - můj relativně triviální use case to vyřešilo.

Co se týče systémovějšího řešení, pořád mám obavu, že ten learning curve není úplně adekvátní situaci typického uživatele, jak si ho představuju - i teď jsem se pro drobné adaptaci příkladů musel naučit základy dost niche jazyka a přitom pochopit (a zčásti si dovodit) datový model systému. Rozumné API by velkou část toho mělo odabstrahovat a nízkoprahově obsloužit to relativně větší množství jednodušších use cases, aniž by se každý musel učit celou raketovou vědu. Dovolím si tedy nechat issue otevřené s tím, že je na vašem poznání uživatelstva, jestlli to budete chtít nějak řešit.

Tak nebo onak by ale výrazně pomohla lepší dokumentace - pokusím se v novém issue naznačit, co by to znamenalo.

Ad distribuce: díky za osvětlení. To je myslím příklad situace, kde by dokumentace pomohla; já jsem si distribuce zjednodušeně představoval jako potenciálně i časové řezy, ale jde o formáty.

[jakubklimek]

@petrbouchal My zase děkujeme za zájem o NKOD. Jednodušší API zvažovat budeme a bude záležet na prioritách, zda a v jaké formě bude implementováno. Issue tedy můžeme nechat otevřené.

Sice to stáčí issue trochu do off-topic, ale nedá mi to. Sice je pravda, že se SPARQL zatím neumí pracovat tolik lidí, jako kolik je schopno se zorientovat v JSON struktuře, na druhou stranu se jedná o webový standard z roku 2008 či v rozumnější verzi 2013, a stejně dlouho je vyučován na univerzitách a velmi rozšířen například v komunitě biologů a chemiků, z univerzálních služeb na něm běží třeba Wikidata Query Service apod. Zda je to niche či rocket science tedy závisí hlavně na dané komunitě. Složitostí/silou je podobný jazyku SQL, hlavní rozdíl je v grafovém datovém modelu (RDF), který pro vývojáře zvyklé na relační či hierarchický není obvyklý, nicméně čím dál větší počet webových standardů ho využívá.

Důležité je ale říct, že na základě RDF dumpů či nad SPARQL endpointem lze budovat libovolné jiné, omezenější API (naopak to jde hůře) - a díky otevřenosti dat to může udělat kdokoliv - nemusí to nutně být provozovatel NKOD. Navíc pak díky standardizaci taková služba může fungovat i s jinými portály otevřených dat, např. https://www.europeandataportal.eu/.

A poslední poznámka k distribucím a dokumentaci - ono to tam je: https://www.w3.org/TR/vocab-dcat-2/#Class:Distribution či https://ofn.gov.cz/rozhraní-katalogů-otevřených-dat/2019-04-04/#položky-metadatového-záznamu.

[petrbouchal]

Rozumím - a rozhodně netvrdím, že SPARQL máte opustit nebo že nejsou uživatelé, pro které je to optimální cesta. Taky chápu, že vám to dává už jinde dohodnuté a vytvořené způsoby tvorby metadat atd., což má svoji hodnotu. Vycházel jsem ale ze svého předpokladu (ověřeného pravda jen částečně) že většina uživatelů, kteří potřebují víc než webové GUI, zároveň nebudou původem informatici, ale často dataři a tvůrci aplikací, kteří jsou zkrátka zvyklí na jiné (a vcelku myslím opravdu rozšířenější) nástroje. Ale to je na nějaký hlubší user research.

Každopádně díky a uvidíme, kam vás zpětná vazba uživatelů dovede.

[jakubklimek]

@petrbouchal Na základě tohoto požadavku jsme zprovoznili GraphQL API. Teprve budeme pracovat na jeho dokumentaci, tak to kdyžtak berte jako "preview" a oceníme k němu i feedback. Názvy klíčů jsou anglicky, jelikož GraphQL zatím bohužel nepodporuje unicode a "cesky" to dělat nechceme.

[petrbouchal]

Díky, fajn že to je k dispozici, zkoušel jsem a ledasjaký jednoduchý dotaz to myslím zastane snadněji než SPARQL, a GraphQL asi pro spoustu lidí bližší nástroj.

[krejpsky-m]

dobrý den,

Jak pokročila implementace JSON API pro datové sady v NKOD?

[jakubklimek]

Dobrý den,

je k dispozici zde v issue zmíněné GraphQL jako alternativa ke SPARQLu. Další API nejsou v plánu.