Open API štandardy

21

A to opravnenie nastavujes prvykrat incialne a potom uz len ziskvas token per komunikciu s API, ano?

Tzn. nemusi klient klikat n krat enrollment ked to vola tretie strana, proste je to opravnenie zaevidovane a uz sa iba vydava token v danom scope.

Takto som si to nejako predstavoval, len som neratal s tym JWT, myslel som ze sa to bude overovat voci AS v ramci komunikacie.

22

Toto by sa dalo ciastocne riesit tym ze sa prinuti strukturovana dokumentacia. Ale spat k tomu procesu, lebo ten bude nasobne narocnejsie definovat. Nieco by mohla riesit takato veta:

  • prevadzkovatel OpenAPI služby musí zabezpečiť čo najnizšiu byrokratickú záťaž a v čo najväčšej miere minimalizovať úsilie vynaložené pre použitie OpenAPI služby

Ďalšia téma pre mňa je licencia. Nakoľko OpenAPI je možné brať aj ako nadmnožinu OpenDataAPI tak tým pádom by tam mala byť pridaná asi aj nasledovná definícia

  • každá OpenAPI služba, ktorá poskytuje dáta musí mať uvedenú licenciu pod ktorou sú dáta poskytované. Poskytovateľ sa zaväzuje využiť licenciu CC-BY alebo CC0 v prípade, že ich použitie nie je v rozpore s platnou legislatívou

Prihlasovanie

  • chceme standardom predpisat len tie sposoby, ktore su dovolene tj. OpenID Connect a STS WS? Musime potom pomenovat akterov/komponenty a zodpovednych za plnenie. Napr. “UPVS je povinne zabezpecit…” alebo nieco v tom zmysle.

Auditne logovanie @jangondol

  • s tymto uplne suhlasim v pripadoch ktore si popisal, tym padom by ale malo byt riesenie centralizovane aby sa to zjednodusilo. Potom sa bavime aj o jednej centralnej gov brane (s tym som OK, len treba aby sa cim skorej zacala robit)

Priklady pouzitia

  • s nutnymi prikladmi uplne suhlasim, ale nie som si isty ze apiary ako take je mozne tam dat nakolko to nie je standard ale komercna aktivita. Da sa ale presne specifikovat funkcionalita, ktoru to musi mat.

Co sa ale tyka Sandboxu tak tam by som to mozno rozvinul, pretoze :

  • jedna moznost je centralne devel prostredie ala UPVS dev, kde ale sahaju vsetci na vsetko a ovplyvnuju sa
  • druha moznost mnou preferovana je ze by Sandbox prostredia boli robene ako docker images s tym, ze klient si moze poziadat o privatny sandbox kde nie je nikto nikym ovplyvneny.
23

Tych tokenov tam moze byt viac, to co ty asi teraz myslis je pristup tretej strany k API aj bez toho, aby si jej to stale potvrdzoval. Na toto pokial viem sluzi refresh token.

V skratke ako to chapem: Tretia strana dostane okrem access_tokenu, ktory moze pouzivat aj tzv. refresh token. Ten moze pouzit ked jej access token vyprsi. Ten refresh token sa nepouziva voci API agendoveho systemu, ale voci vydavacovi tokenov, kde si proste vypyta novy access token.

Toto ma dve vyhody:

  • agendovy system o tomto nemusi tusit vobec nic. jemu vzdy pride access_token
  • tretia strana aj tak musi ziadat o access_tokeny od endpointu na tokeny. ak chce offline pristup, tak si musi zabezpecit udrziavanie aktualnosti tokenu. ak sa clovek rozhodne zrusit pristup tak jednoducho refresh token prestane fungovat, nedostane teda tretia strana novy access token a tym padom sa do ziadneho agendoveho api uz nedostane. Cize revokacia je vyriesena.

Tento model je inak presne to ako funguje STS token na UPVS (v spojeni OnBehalfOf) len to neni brutalne kosate WSDL/SOAP ale pomerne lahke spravit si to aj na kolene (su to pre tretiu stranu 2-3 requesty). Ale ako sa hovori - bezpecnost si nikdy nerob sam, ale pouzi kniznicu.

24

No tak uz mas specku ;).

No a este dorobime to, ze tretia strana proaktivne vyzve klienta (ziadost o opravnenie iniciovane tretou stranou a nie klientom), aby jej udelil opravnenie na pristup k nejakej sluzbe v ramci osobnej zony, kde uz iba prejavi volu, nechanizmus je ten isty len komunikacia na klienta opacna.

Takze ako klient budes iba klikat ano/nie ;).

25

Je na to sice ina PS, ale KS ISVS riesi aj procesy, cize spomenieme a potom si to uz KS ISVS “sprocesuje”. :slight_smile:

Tak urcitee. Ale vazne: Ano. Len teda treba koordinovat s @juraj.bardy, kedze “audit trail” a jeho prezeranie obcanom ma v scope (zatial) koncept “My Data” (@jsuchal uz napisal).

Tu ale mame riziko, ze zachadzame na “prilis vysoky level” (obdobne ako API GW spomenuta @ret vyssie) a teda uz hned v prvom kroku si nalozime privela (celostatne integrrovanie riesenie s mnozstvom features) a tym padom nakoniec niz pouzitelne nedosiahneme.

Povedane inak, ja by som sa snazil na zaciatok “KISS” (zadefinovanie zakladneho konceptu) a zbytok vynechal alebo len “naznacil” (v nejakej nepovinnej omacke). A zbytok nechal na “nasledujuce kroky”.

Cize nateraz by som spomel cosi typu “Open API sluzba musi zabezpecovat ukladanie informacii o volaniach (kto, kedy, preco, s akym opravnenim, cie udaje, ktore presne udaje, a pod.) a.k.a. audit-trail. Audit-trail bude neskor pouzity sluzbou “My Data” (vid Trello)”.

Ano, pristup ako pristup. Lognut treba. (aby sme nemali “dvojaku kvalitu” :slight_smile: )

Ale aby to obcanovi davalo zmysel, musi byt z logu jasne kto a s akym opravnim k udajom pristupoval (priklad “MV SR na vlastne meno, kvoli agende X, pristupovalo k udaju o vasom trvalom pobyte”, “apka XYZ na zaklade opravnenia od obcana ABC, pristupovala k udaju o datume narodenia”).

Radsej nie. Max. staci “hint/odkaz” na GDPR.

Gro udajov bude totiz zrejme informacie o konkretnom obcanovi resp. jeho privatna agenda a teda z principu nie Open Data. A ak k tomu budu “prilepene” nejake anonymne udaje (napr. ciselnikove: z RA, RPO atd.) tak zase tie su dohladatelne separatne, aj ako Open Data a teda aj s riadnou licenciou (plus by malo byt pouzite URI, cize vieme kam mame ist).

Dalej, GDPR “definuje” (nie som pravnik, ale tak to chapem) ze data o mne su “moje data” (“moje” ako “majetok”). To je vcelku jasna “licencia”, t.j. cokolvek si o sebe stiahnem z Open API je moje a mozem to nasledne zverejnit (ak chcem) alebo nezverjnit (ak nechcem), alesdbo cokolvek dalsie (tapetovat si s tym byt, a pod.)

Specialna katerogia mozu byt 3rd party, ktore v mojom mene budu liezt cez Open API do ISVS. Opat, z titulu GDPR oni budu spravovat udaje o mne, nebudu vlasnikmi tychto udajov. Cize s udajmi nebudu moct robit nic o com neviem a na co im nedam suhlas. (Tot teoria GDPR od nepravnika, amen.)

Tak ako Open Data by mala publikovat ta PO, ktora ich primarne spravuje (kvoli “latencii”, “garanciam”, efektivite, atd. - ale ma mat ponechanu volnost, ze ci si to spravi sama, alebo sa dohodne naporl. s NASES) tak aj logovanie by urcite malo byt robene rovno v systeme kde je primarna agenda (tot aby boli v logu aj ti, ktori z nejakeho titulu obchadzaju povedzme napr. potencionalnu centralnu API GW). A ze ci potom “My Data” riesnie bude vytahoval logy z X systemov napriamo, ci on-line alebo cez nejake nocne batche, to uz nechajme na “My Data”.

Hlavne treba zabezpecit, aby auit-trail bol, vzdy a vsade a v dostatocnej kvalite a aby bolo vzdy jasne, ze v danom ISVS ho ma na zodpovednosti tato konkretna VS (lebo distribuovana zodpovednost je zidna zodpovednost aj preto tu potom mame odposluchove systemy kde chodi kadekto a vojaci, policajti ci SIS sa vsetci svorne tvaria ze to nie oni, ze oni nic, ze to niekto iny).

26

Osobna zona nie je z tohto pohladu len dalsia “tretia strana”? Lebo tie opravnenia sa aj tak musia schvalovat niekde v tom komponente ktory udrziava opravnenia, vydava tokeny. To v principe moze byt hocikaky “identity provider” aj ked tu je ziaduce aby bol jeden.

27

Hmm… takze sme spravili “Moje data” == “OpenAPI”? Cez OpenAPI si predsa viem vyziadat aj kde sa aktualne nachadzaju vlaky/autobusy, info o firme, zoznam faktur a N dalsich veci. Suhlasim ze pri osobach a jej osobnych udajoch je to viazane na GDPR, ale je to len jeden z usecases ako to chapem ja. Preto mi pride textacia “platna legislativa” vseobecnejsia a pokryva vsetky scenare. Co sa tyka licencii tak aj ITMS2014 publikuje v principe data cez API a pre taketo data by mala byt licencia nie? Alebo ako viem co mozem robit s tymi datami?

Vyriesme preto teraz vseobecny specifikaciu OpenAPI s tym, ze jasne ze treba uvazovat aj usecase “Moje Data” ale nebrat ho ako jediny. Napriklad co sa tyka tej popisanej authentifikacie tak tam je mozne robit aj nie je potrebne robit s osobnymi udajmi. Niekto mozno bude vyzadovat prihlasenie aby vedel trackovat, kto kolko coho pozera a ako zatazuje server a podobne. Mozno ze niektore veci budu zasa spoplatnovane (vypis z registra trestov) takze aj tam by to malo byt nejako zohladnene.

28

Osobna zona = FE, kde to kliknes, a ten komunikuje s mikrosluzbami v komponente, ktory udrziava opravnenia a schvaluje ich.

29

Asi si neviem uplne predstavit ten scenar. Vies priklad?

30

OK, tu mi to uslo, kedze uplne rovnikto medzi “My Data” a “Open API” asi dat nemozeme.

Ale zase “kde su vlaky” nie je Open API, to je Open Data API. Jedine ze by som volanim toho API mal moznost vlaky aj pridavat, uberat a presuvat. :slight_smile:

Detto API ITMS2014+, to je “Open Data API”.

Napada niekoho este nejaky use case, ktory nie je ani “Open Data” ani “My Data” a predsa zapada to “Open API”?

Konceptualne je toto IMHO kompetencia “Open Data API” a nemiesal by som to do “Open API”.

O.i. aj preto, ze pripadny “rate limiting” sa tyka aj “webov” (t.j. human readable udajov, poskytovanych typicky v HTML). Toto podla CSIRT.SK ISVS robit maju (lebo ako inak chcu zarucit ferovu dostunost a odolnost voci utokom?), ale nateraz zvycajne nerobia. Ak by sme teda chceli toto riesit, tak by som preferoval separatny dokument “o security”, ako temu “len pre” Open API ci Open Data API by som to radsej nerozvadzal. Inak sa nam bude nabalovat scope (a dosledky uz som popisal vyssie).

31

Ty teda vravis, ze OpenAPI je LEN na read/update sukromnych dat? Ja osobne to chapem tak ze :

  • OpenData API ma restrikciu len na read
  • OpenAPI vie read ale narozdiel od OpenDataAPI vie este aj update.
    Inak si predstavujem pravidla uplne zhodne. Podla mna totiz zanesieme len zbytocny pojem navyse.

Podme teda najst a jasne standardizovat aj definiciu pre OpenData API ak to chceme rozlisovat a uplatnovat na to odlisne principy.

32

Ano, konceptualne by som to razil tymto smerom. Vid navrh definicie (Open API štandardy - #5 by hanecak).

Lebo konceptualne je teda “read only” vs. “(najma) write” dost velky rozdiel. A kym pri implementacii chceme tlacit na dodrziavanie rovnakych principov pri oboch (KISS, REST, JSON, …) tak ten konceptualny rozdiel nakoniec v detailoch moze tlacit na odlisne riesenia, vid niektore veci spomenute vyssie, napr.:

  • OAuth, OpenID Connect, SOAP/WS + STS (Open API štandardy - #4 by jsuchal): Pre “Open Data API” IMHO plne staci OAuth a aj to len volitelne (kedze ide najma o pripadny “rate limiting”) a ostane veci by uz boli “overkill” a ak ich zacneme zanasat do “Open Data” speciek, tak nabobtnaju a zabrzdi nam to zverejnovanie datasetov.
  • “reprezentuje elektronickej služby verejnej správy prístupné verejnosti” (Open API štandardy - #7 by msurek) je IMHO ine ako “reprezentuje dataset” (55/2014 Z. z. Výnos o štandardoch pre informačné systémy verejnej správy) - a toto by sme myslim mali zdoraznit
  • procesy pre “Open Data” opat suvisia, ale su predsa len vyrazne ine pre "data "a pre “sluzby” (narazajuc na “Neviem nakolko riesi standardizacia aj procesy” v Open API štandardy - #9 by jsuchal , navyse procesy nie su len o tom co vidi obcan, procesy maju pokracovania aj v neverejnej casti, “pod hladinou”)
  • SLA: SLA pre sluzbu (Open API) asi bude zlozitejsia nez pre data (Open Data API)
  • povinne logovanie/audit-trail: pre Open Data API nie je audit-trail kriticky (a asi bude casto rat zbytocny), pre mnohe Open API zrejme kriticky bude
  • atd.

Kedze “Open Data” use-cases ocakavam vyrazne viac nez tych “Open API”, tak by som tie dva koncepty rad drzal oddelene (ale prelinkovane :slight_smile:), aby sme tych co budu riesit “Open Data” nezahltili a nedomotali vecami, ktore maju zmysel len pri “Open API”.

Hladame teda taku definiciu, ktora co najviac vystihne “odlistnost” Open API od “Open Data API” (a “G2G API”) a nasledne bude referencovat tie ostane tak, aby sa pri nalsednom realnom SW developmente co najviac “reusovalo”.

[ Ono ano, nakoniec tie veci dostane mozno ten isty architekt a ten isty developer, ktori budu robit nejaky novy ISVS a budu v nom poziadavky aj na G2G, aj na Open API a aj na Open Data API. Tak im potrebujeme dat kratke do seba zapadajuce texty na zaklade ktorych im to (ako dobre platenym chytrim ludom) rychlo “dopne” a budu vediet, ze asi nemaju robit tri rozne API na kazdy use-case, ale ze maju vhodne vymixovat len jedno API. :slight_smile: Aj ked ano, v niektorych pripadoch im z toho predsa len mozu vyjst API 2, prip. mozno aj 3. A mozno to pri tych mamutich projektoch dostanu rozni ludia a nenapadne ich to spojit. Pri generalizovani s tym musime ratat. ]

2 Likes
33

Chapem sice co chces dosiahnut, ale bojim sa ze namiesto poriadku spravime len vacsi zmatok. Treba to isto premysliet ze ci ma zmysel to oddelovat.

Osobne si myslim ze aj pre OpenAPI mozeme stale vraviet o prevazne read requestoch (kedy som objednany k lekarovi, co sa deje s mojim majetkom, kedy mam ist na STK,… ) a write operacii bude isto stale menej. Kriterium preto “najme write” byt nemoze.

Ked sa bavime o “reprezentuje elektronickej služby verejnej správy prístupné verejnosti”, tak v principe ak by to bol staticky file tj. iba Open Data tak beriem ze to nesedi, kedze ale tam sa to da parametrizovat a az sluzba ti na zaklade realtime requestu vrati to o co si ziadal tak to stale sedi.

Ked sa bavime o OAuth vs OpenID Connect tak v principe to zasa nie je vobec velky rozdiel kedze jeden je len mierna nadstavba toho druheho ale urcite nie radikalne.

Pre mna dava skorej vyznam ze “Open Data” je staticky periodicky davkovy export do suboru. “Open API alebo Open Data API” je realtime sluzba, kde sa kladu v principe dost podobne (ak nie vo vacsine pripadov aj identicke) naroky na prevadzku a tym padom nema zmysel ich nazvoslovne oddelovat.

34

…urcite ma…je to uplne legitimna poziadavka…dokonca aj vizualne pre pouzivatela by to malo byt pristupne…udeli tretiemu subjektu pristup, tak by mal mat moznost vidiet ako tam ten subjekt pristupuje…

35

Skusim este iny pohlad. Co takto to len zaviest ako rozne urovne Open API a pre kazdu uroven zaviest pravidla. podobne ako 5 star :wink:

  • level 1: chcem pristupovat k verejnym datam/sluzbam cez api. toto je to co volate Open Data API. netreba tuto okrem standardizacie “wsdl” velmi nic moc.
  • level 2: chcem pristupovat k neverejnym datam/sluzbam ale plosne: toto je privatne api (v principe netreba velmi vymyslat s consent screenom, staci api kluc/bearer token). prikladom budiz API vestnika VO, ktore je sice verejne dostupne ale az potom ako si vypytate token.
  • level 3: chcem pristupovat k neverejnym datam/sluzbam za niekoho: toto je svaty gral (treba consent screen, vydavanie tokenu sa riadi specialnymi poziadavkami, aplikacia musi byt niekde zaregistrovana, etc…)

Ano write operacie mozu niekoho vystrasit, ale z techickeho-standarizacneho pohladu tam ziadny rozdiel nevidim.

2 Likes
36

OK, cize vecer sa ideme pobavit, ci je dolezite vysvetlit konceptualny rozdiel medzi “poskytovanie sluzieb” (Open API) a “poskytovanie udajov” (Open Data / Open Data API) alebo sa zamerat na to, ze v oboch pripadoch (najma teda ak sa aj data poskytuju cez API) su obe velmi podobne a teda vlastne len:

  1. “doplnime” nejaku “zakladnu definiciu Open API” (ako uvodnu omacku) a nasledne uz len
  2. cielime na to, aby vo Vynose pribudli veci potrebne pre “write”, t.j. najma tie co spomenul @jsuchal tu: Open API štandardy .

To druhe (pridanie konkretnych poloziek standardov do Vynosu) je vlastne ciel (to je “core scope” standardizacie), cize s “omackou/definiciou” sa velmi parat nemusime (to je skor scope “strategie” a teda napr. NKIVS) a k pivu sa dostaneme rychlejsie. Sedi?

Teraz k tomu, co vo Vynose je a co treba IMHO pridat:

  • REST, JSON, SOAP, WSDL a XML uz vo Vynose su, cize treba pridat napr. OAuth.
  • Mame tam §52 pre otvorene udaje, pridal by som teda separatny § pre Open API, minimalisticky
  • § 13, b) asi bude treba prekopat, kedze pridanim Open API by uz bol prilis komplikovany. Idealne asi tym, ze sa vypusti “pri otvorených údajoch je možné použiť aj” (cim sa odstavec vyrazne zjednodusi a navyse sa JSON a CVS sa stanu plnohodnotnou moznostou aj pre G2G)
37

Suhlas, treba to takto odstupnovat ale nevymyslat tomu rozne mena nech sa nezamotame.

Za mna netreba vysvetlovat rozdiel medzi suborom a API (ale kludne mozeme napisat ze OpenData je mozne chapat ako data v subore a OpenAPI ako realtime dopytovanie s parametrizaciou sa pre ziskanie datasetu) a co sa tyka API tak sa len podme pobavit o nejaky odbornych definiciach pre tie urovne.
Kazdopadne beriem si notebook, nech to vieme rovno aj spisat nech z toho strenutia definicia vznikne co najviac ucelene a potom to sem mozeme pastnut ako dalsiu verziu navrhu.

1 Like
38

Stretnutie k tomuto bude dnes (27.10.) o 17:30 v Drag, Stare Grunty 64, Bratislava (nedaleko MFUK).

40

Na zaklade stretnutia som vypracoval prvotny draft špecifikácie OpenAPI a OpenDataAPI na pripomienkovanie. Hodil som ich rovno na confluence PS1 skupiny:
OpenAPI
https://wiki.finance.gov.sk/display/PS1/OpenAPI
OpenDataAPI
https://wiki.finance.gov.sk/display/PS1/OpenDataAPI
Rozdiel medzi OpenDataAPI a OpenAPI
https://wiki.finance.gov.sk/display/PS1/OpenAPI+vs+OpenDataAPI

@Lubor @jsuchal @hanecak - pozrite si ci sme sa na stretnuti rozumeli a zapisal som to ako sme sa bavili.

Samozrejme aj dalsie pripomienky su vopred vitane.

41

mám len potrebu tu spomenúť, to čom už spomínal inde viac krát:

  • ak si pri elektronických službách rozoberieme čo je to zápis, tak dospejeme k záveru, že jediným spôsobom ako niečo zapísať je podať podanie. Preto usudzujem, že API na zápis už máme (akurát je generické - ÚPVS+SkTalk) a stačí ho otvoriť
1 Like