Zopár základných tipov a odporúčaní na to, ako do projektu zapracovať Open Data API:

Pre podrobnejšie informácie kliknite na linku, ktorá Vás zaujíma.

Zverejniť treba všetko, ideálne v "raw" podobe

Zverejniť údaje v "raw" podobe má dve základné výhody:

• ľahšie dodržíte pravidlo "nerobte veci dvojmo" (viď nižšie), zverejníte to čo máte a ako máte a netreba na to míňať veľa extra zdrojov
• z "raw údajov" sa dá vygenerovať takmer hocičo (typicky rôzne štatistické sumáre a priemery), ak ale zverejníte len povedzme sumáre a priemery, už sa z toho nedajú spraviť takmer žiadne ďalšie štatistiky, analýzy či aplikácie
  • výnimkou sú samozrejme údajové zdroje, v ktorých sa vyskytujú osobné údaje či utajované skutočnosti - v takých prípadoch sa robí anonymizácia a teda zverejňujú sa len určité agregované údaje a pod.

Poskytnite tri základné operácie

Pre každý typ objektov resp. tabuľku (podľa údajového modelu) budú užívatelia API chcieť najmä tieto tri základné volania:

1. daj mi zoznam všetkých objektov (t.j. zoznam ID)
2. daj mi všetky podrobnosti k objektu s týmto ID
3. daj mi zoznam všetkých objektov (t.j. zoznam ID) ktoré boli zmenené od "dátum + čas!"

Akékoľvek ďalšie volania (rozne filtrovania, vyhľadávania atď.) sú skôr bonusom, ktorých pridanie by malo byť podložené reálnym dopytom (viď časť "konzultujte s používateľmi").

K zoznamom (volanie 1 a 3) samozrejme treba implementovať tzv. "paging" a to či už klasicky pomocou OFFSET + LIMIT alebo trochu chytrejšie pomocou správneho zoradenia a "last seen ID" (viď http://use-the-index-luke.com/no-offset).

Použite REST a JSON

SOAP je v "enterprise" super a štandard, ale pre bežné "webové veci" - a teda aj Open Data - je to zvyčajne zbytočný "over-kill".

Preferovaný je teda RESTfull pattern a JSON, ako minimum.

Ak okrem JSON viete poskytnúť aj iné "serializácie" (XML, CSV, ...) je to zvyčajne vítané.

Vítané je aj použitie Hypermedia, ktoré umožní "objaviť" funkcie v API bez štúdia dokumentácie. Viď https://en.wikipedia.org/wiki/HATEOAS .

Zverejňujte súbory aj API, ak sa dá

Zvyčajne sa dá zverejňovanie otvorených údajov implementovať ľahko oboma spôsobmi:

1. súbory (dumpy): pomocou pravidelného exportu do súborov (napr. SQL SELECT + tzv. cron, výsledok do CSV)
2. API: jednoduché read-only API nad interným modelom údajov, čosi ako R vyňaté z CRUD

Každý zo spôsobov oslovuje inú "cieľovú skupinu" (CSV sú schopní a ochotní otvoriť aj bežní ľudia, API pomáha najmä programátorom získať efektívne práve tie údaje ktoré potrebujú) a možnosť voľby je zvyčajne vítaná.

V ojedinelých prípadoch niektorá z možností nie je efektívna: špeciálne API pre malé primitívne tabuľky zvyčajne robiť netreba a výroba (a sťahovanie) dumpov sú od určitej veľkosti (povedzme od pár sto MB) už oštarou.

API sa tiež dizajnuje ťažšie ak ešte nie je úplne jasné, komu a na čo by údaje boli. Ak si nie ste istý, spravte na začiatok len dumpy.

Prípadné ďalšie čítanie: Publishing Open Data – Do you really need an API? .

Nevymýšľajte koleso, pozrite sa ako to robia iní

Inšpirujte sa tým, ako to robia iní, viď napr.:

• všeobecne REST+JSON API použité v API GitHub: https://developer.github.com/v3/
• Open API GOV.UP Pay: https://gds-payments.gelato.io/reference/docs/this-documentation
• Open Data API RegisterÚZ: http://www.registeruz.sk/cruz-public/version/186074/static/api.html

Snažte sa postupovať podľa odporúčaní a štandardov z iných krajín (o.i. sú zvyčajne spracované lepšie a do väčšej hĺbky než táto stránka):

• USA: https://github.com/18F/api-standards
• UK: https://www.gov.uk/service-manual/making-software/apis.html

Skúste použiť nástroje, ktoré vám uľahčia prácu a pomôžu vám vyvarovať sa bežných chýb:

• https://apiary.io/
• https://getsandbox.com/
• Swagger, vid napr. https://generator.swagger.io/?url=https://govbox.slovensko.digital/openapi.yaml

Nezabúdajte na dokumentáciu

Okolo API netreba vypisovať veľkú dokumentáciu: Pri dobrom návrhu je možné správne uhádnuť mnoho vecí rovno z URL a z údajov, ktoré z daného URL získame. V dokumentácii však predsa len niečo musí byť, napr.:

1. popis spoločných patternov, ktoré sú rovnaké v celom API
2. zoznam všetkých volaní (ideálne v kombinácii s "hypermedia", skúste napr. `curl https://api.github.com`)
3. popis odchýliek od spoločných patternov (+ zdôvodnenie, aby bolo jasné)
4. popis údajového modelu: aké sú väzby medzi jednotlivými objektami či tabuľkami, atď.
5. ...

Podrobnejšie odporúčania k tvorbe dokumentácie dáva napr. GOV.UK na adrese https://governmentasaplatform.blog.gov.uk/2016/01/14/improving-developer-documentation/ .

Viď tiež dokumentáciu k už spomínaným príkladom:

• https://developer.github.com/v3/
• http://www.registeruz.sk/cruz-public/version/186074/static/api.html
• https://generator.swagger.io/?url=https://govbox.slovensko.digital/openapi.yaml

Nerobte veci dvojmo, raz pre "internú potrebu" a potom pre Open Data (a.k.a. "API first")

Najmä ak realizujete kompletne nový projekt, má zmysel uplatniť pravidlo "API first" a neimplementovať Open Data API ako čosi "navyše".

Ak napríklad realizujete portál, kde sa nejaké údaje zobrazujú, vyhľadávajú, filtrujú a vizualizujú, má zmysel rozdeliť portál na back-end a front-end. Back-end pracuje s údajmi a poskytuje ich front-endu cez API. Urobte to API pre svoj front-end a to isté API potom poskytnite aj pre Open Data.

Tento prístup vám zároveň uľahči rozhodovanie, ktoré údaje zverejniť: skrátka tie, ktoré portál zobrazuje. Kým však portál údaje zverejňuje v "human readable" podobe (HTML + obrázky), API zverejní tie isté údaje v "machine readable" podobe (JSON, CSV, ...).

Uplatnenie "API first" následne znižuje náklady na prevádzku a support.

Plus viď ďalší bod:

Konzultujte s používateľmi, robte agilne

Čokoľvek ste či už zverejnili ako Open Data API alebo to len plánujete zverejniť, počítajte s tým:

• že sa vám ozvú "nejakí ľudia"
• že niektorí z nich budú mať zmysluplné pripomienky
• že tie zmysluplné pripomienky bude treba zapracovať a zverejniť novú verziu API
• že kôl "prišli pripomienky, posúdili sme a zapracovali do novej verzie API" bude viac

To o.i. vyžaduje aj dodržať ďalší bod:

Zverejnite beta verzie v dostatočnom predstihu pred termínom dodania finálnej verzie

Máločo sa podarí na 100% hneď na prvý krát. Ak ľudí prekvapíte tým, že zverejníte len finálnu verziu API bez predchádzajúceho testovania a pripomienkovania:

1. budú sa vám ťažko zapracúvať zmeny (po oficiálnom konci projektu sa zvyčajne už dajú robiť len drobné opravy vrámci supportu, čo nemusí stačiť)
2. budúci používatelia môžu byť aj nahnevaní, často krát právom

Pozrite si Výnos 55/2014

Výnos slúži ako vodítko pri veciach, ktoré nemusia byť úplne jasné.

1. API, t.j. REST a JSON sú vcelku jasné. Ale napr. CSV má ale veľa variant, preto tento štandard pre ISVS niektoré veci upresňuje (viď prílohu Výnosu č. 5).
2. Ďalej je tiež dôležité, že pri údajoch ktoré pribúdajú, menia sa a neskôr sú prípadne rušené nestačí údaje len prepísať či zmazať. V takých prípadoch je potrebné indikovať, kedy bol údaj pridaný, zmenený, "vymazaný" (rozumej "údaj ostáva v datasete, ale je k nemu priradená informácia o tom, že už neplatí") a pod., viď § 53, bod g. Typicky je teda dobré pridávať stĺpce typu "modification timestamp", príznak "deleted" a pod.
3. ...

Viď teda http://www.informatizacia.sk/standardy-is-vs/596s .

Ďalšie zdroje

• Open API recommendations for cities by six largest cities in Finland: https://www.databusiness.fi/content/uploads/2017/10/20171116_APIrecommendations_WEB.pdf

• GOV.UK: API technical and data standards: https://www.gov.uk/guidance/gds-api-technical-and-data-standards

Credits (v abecednom poradí): Hanečák Peter, Illek Lubor, Suchal Jano