Komisia pre štandardy ISVS - PS1

Spolupráce so štátom a samosprávami
41

Pri ITMS nehovorime o datasetoch, ale o OpenAPI co je rozdiel, ktory ma trochu ine pravidla a mozno ze aj to vyvolava nepochopenie v niektorych pripadoch. Kazdopadne rovno popisem viziu maximalneho mozneho navrhovaneho scenaru pre API a vlastne celeho jeho zivotneho cyklu s 5 hviezdickami.

  1. Prva vec, je popisat sluzbu standardnymi metadatami, ktore predpisuje EU (Core Public Service Vocabulary 2.1). V principe je to velmi podobne ako pri datasetoch, kde je tiez nejaky standard pre metadata datasetov a tieto sa vzdy nachadzaju v samotnych datach. Toto je mozne povazovat za byrokraciu, ale nic extra strasne.

  2. Druha vec je, ze vsade kde sa pouzivaju teraz ciselne identifikatory, tak tie by boli nahradene referencnymi URI identifikatormi co je minimalna narocnost nakolko len ID z integer bude zrazu URI. Teda v pripade ze sa hovori o referencnych udajoch napriklad dodavetelId je asi referencny identifikator firmy (z nazvu ani popisu mi to nebolo zrejme).

Ukazka pre https://opendata.itms2014.sk/swagger/?url=/v2/swagger.json#!/subjekt/dodavatel_show

Vstupne parametre
dodavatelId : 50158635

Po novom :
dodavatelId: https://data.gov.sk/id/legal-subject/50158635

Vystupne parametre analogicky, pouzije URI identifikator namiesto ciselneho

  1. Treti a zaroven aj posledny krok je zaregistrovanie sluzby v MetaIS. To znamena, ze tu sa vlastne vyplnia metadata spominane v bode 1. Popisanie rozhrania cez OpenAPI specifikaciu (opensource nastupca Swaggera co teraz ITMS pouziva - v principe Swagger 3.0). Premapovanie vstupno/vystupneho rozhrania na datove prvky centralneho modelu cez jednoduche graficke rozhranie.
    Premapovanie je asi nasledovne :
    Takto vyzera skrateny vystup sluzby show_dodavatel
    {
    “createdAt”: “1994-10-17T22:22:30+01:00”,
    “ico”: “Eos voluptatem rerum voluptate et ipsum saepe.”,
    “id”: 7417765646913339000,
    “nazov”: “Totam id.”,
    “obec”: “Omnis ducimus consectetur voluptatibus.”,
    “psc”: “Beatae repellendus distinctio.”,
    “stat”: “Quis omnis quia minima.”,
    “ulica”: “Velit aperiam laborum est commodi.”,
    “ulicaCislo”: “Expedita est quia rerum sed.”,
    “updatedAt”: “2006-06-09T08:13:50+02:00”
    }
    v principe to bude formular na mapovanie v MetaIS kde sa povie (samozrejme s autocomplete, napovedou a podobnymi zlahcovakmi + supportom datovej kancelarie)
    createdAt = http://purl.org/dc/terms/created
    ico = https://data.gov.sk/def/ontology/legal-subject/legalIDCode
    nazov = https://data.gov.sk/def/ontology/legal-subject/name
    …

Co tieto poziadavky riesia:

  1. zladenie so standardmi EU
  2. pekna strukturovana dokumentacia (tu uz ITMS ma, a su krasny priklad ze takto by sa to malo robit povinne pre vsetky sluzby)
  3. centralizacia do MetaIS - meta uz teraz registruje sluzby tak preto ona. Zaroven sa tak stane developerskym portalom s peknou dokumentaciou a nie len kopou balastu a kazdy bude vediet kde ma hladat bud OpenAPI alebo akekolvek API
  4. Pouzitie referencny URI identifikatorov jednoznacnych v celom SR
  5. Popisovanie rozhrania s Centralnym modelom tj. datove prvky reprezentovane cez jednoznacne URI:
  • stat ma prehlad o datovych tokoch v krajine
  • vie ktore systemy ake data pouzivaju a tak vie aj lepsie pomenovat ze ktory by mal byt zdrojovy, resp. ktory udaj by mozno mohol byt referencny, co by znamenalo ak by napriklad chceli zmenit “rodne cislo” na “bifo” lebo by vedeli kde vsade sa rodne cislo teraz pouziva a kde vsade to potom bude treba zmenit.
  • moznost robit centralizovanu validaciu - ked bude Centralne povedane ze meno ma 255 znakov, tak po takomto mapovani moze byt tento “constrain” automaticky aplikovany aj na dany atribut. Vsetci budu pouzivat rovnake obmedzenia a datove typy pre tie iste elementy.
  • jednoznacnost atributov a ich popisu (nazov = meno firmy, dodavatelID = referencny identifikator…) tj. kazdy vie ake data sa maju v atributoch posielat aj bez dodatocnej dokumentacie

Rad by som trosku blizsie hlavne rozviedol temu OpenAPI, pretoze do tohto konceptu v principe zapada aj dereferenciacia URI (https://wiki.finance.gov.sk/pages/viewpage.action?pageId=20023176) kde ak si zadam URI firmy do prehliadaca a do hlavicky podhodim Content-Type: application/json tak by som dostal vlastne JSON objekt o datach o firme. Podla mna by sa to v tom momentalne zacalo vsetko pekne zlievat. Po prestudovani toho navrhu (prosim citat az po koniec aj cast Dynamicka dereferencia) je mozne OpenAPI spojit aj tymto sposobom pre referencne URI.
V principe ak chcem dostat z RPO vsetko so Slovensko Digital tak zavolam sluzbu ako :
GET
https://data.gov.sk/id/legal-subject/50158635
Content-type: application/json

dostanem info ako OpenAPI v JSONe. V principe by vlastne OpenAPI a referencne identifikatory mohli byt pouzivane na volania. Co na ten koncept hovorite? @jsuchal @anton-somora @kyselat

1 Like