Jakelutavat: tiedosto ja rajapinta
Avointa dataa (tietoa) voi jakaa kahdella tavalla: tiedostona ja rajapinnan avulla. On olemassa myös rajapintoja, joiden avulla jaetaan tiedostoja. Usein datan avaajat miettivät, pitäisikö data avata rajapinnan vai tiedoston avulla. Seuraavaksi vertaillaan näitä keskenään.
Jakelutavan valinnassa auttaa, kun miettii tarvetta. Uudessa avoimen datan direktiivissä dynaamisessa tietoaineistoissa suositaan jakelua sekä tiedostona että rajapinnan kautta. Tämä on järkevää, sillä tiedostoja osaa tyypillisesti käsitellä paljon suurempi määrä datan hyödyntäjiä kuin rajapintaa. Alla olevassa taulukossa on pyritty suuntaa antavasti vertailemaan näitä kahta.
|
|
TIEDOSTO |
RAJAPINTA |
| Suuntaa antava metafora? |
“Vesipullo” “valokuva” |
“vesihana” “video” |
|
Miten nopeasti tieto muuttuu? |
Korkeintaan kerran päivässä |
Tyypillisesti useita kertoja päivässä |
|
Kuka / mikä tietoa uudelleenkäyttää? |
Ihminen |
Toinen ohjelma |
|
Mitä tiedon käsittelytapoja tuetaan? *riippuen pääsyoikeuksista |
Tiedon haku |
tiedon haku (joskus myös muokkaus, lisääminen ja poisto rajapinnan kautta)* Tyypistä riippuen jo kutsuihin perustuva (REST / GraphQL) tai striimaava (Websockets). |
|
Tyypillisin |
CSV |
JSON |
|
Tiedon sisältö |
Vakioitu. Tiedostossa on selkeä alku ja loppu. |
Räätälöitävissä. Ei aina selkeää alkua ja loppua. Voi olla jatkuva “tietovirta” |
|
Käsittelyn vaikeus datan hyödyntäjälle? |
Helpompi |
Vaikeampi |
|
Datan hyödyntämiseen vaadittava sovellus- |
Tiedostoja pystyy usein käsittelemään suoraan esimerkiksi toimisto-ohjelmilla, eikä varsinaista ohjelmistokehitystyötä usein tarvita. |
Jos rajapinta on suunniteltu helppokäyttöiseksi, voi sen käyttö onnistua ilman ohjelmointia. Yleensä rajapintojen hyödyntämisessä tarvitaan ohjelmointitaitoa ja ohjelmistokehitystä. |
|
Esimerkkejä |
Postinumerot, kadunnimet, äänestystulokset, tilastot, kierrätyspisteet ja luonnonsuojelualueet kartalla |
Julkisen liikenteen kulkuneuvojen reaaliaikaiset sijainnit, sääennusteet, yritystiedot |
|
Tyypillinen tiedon |
Visualisointi, laskenta ja tiedoston yhdistäminen |
Sovellukset, visualisointi, tietojärjestelmien uudelleenkäyttö, yhdistäminen, analytiikka, koneoppiminen (tekoäly), äänikäyttöliittymät. |
Tiedosto
Tiedostot ovat helpoin tapa jakaa ja hyödyntää tietoa. Useimpia tiedostoja pystyy käsittelemään suoraan erilaisilla ohjelmistoilla. Tiedoston julkaisun voi automatisoida. Yleensä julkaisu on selkeä prosessi ja helppoa tehdä säännöllisesti. Esimerkiksi palvelimella voidaan automatisoida tiedoston tuottaminen ja sen lisääminen rajapinnan avulla Avoindata.fi palveluun. Tiedosto säilyttää historian helposti. Tiedostolla on selkeä alku ja loppu.
Erilaisia teknisiä rajapintoja
Suomen kielessä rajapinnalla on useampi semanttinen merkitys ja siksi tässä dokumentissa käytetään käsitettä tekninen rajapinta. Rajapinnat sopivat suurien tietomäärien käsittelyyn, jolloin rajapinnan avulla tietojoukosta voidaan poimia sopiva osajoukko. Rajapinnan hyödyntäminen vaatii usein paljon teknistä osaamista.
Teknologioita toteuttaa rajapinta teknisesti on useita erilaisia. Kaikista yleisin ja käytetyin avoimen datan jakelussa on Restful-arkkitehtuurityyli. Suomessa avointa dataa jaetaan lähinnä yksittäistapauksissa palvelimen ja selaimen välisillä WebSocket-yhteyksillä ja GraphQL-rajapintateknologialla. Joissain vanhemmissa järjestelmissä voi olla käytössä WSDL/SOAP-teknologiaa, mutta sen merkitys avoimen datan jakamisessa on pieni. Alla olevassa taulukossa on vertailtu erilaisia rajapintateknologioita toisiinsa.
Taulukko. Erilaisia rajapintateknologioita.
|
REST (REpresentational |
WebSocket |
GraphQL |
WSDL/SOAP (WSDL = Web Services Description Language) |
|
|
JULKAISUVUOSI |
2000 |
2012 |
2012 (Facebookin ulkopuolelle vuonna 2015) |
2000 |
|
ALKUPERÄ |
Roy Fieldingin väitöskirja (Architectural Styles and the Design of Network-based Software Architectures). Ja varsinkin väitöskirjan luku 5. |
Internet Engineering Task Force |
Facebookin työntekijä Lee Byron. |
IBM, Microsoft ja Ariba |
|
IDEA |
|
Selaimen ja palvelimen reaaliaikainen datan virtaus molempiin suuntiin Ei tarvitse erikseen kysyä päivityksiä |
Kaikki tieto on saatavilla yhden päätepisteen (URL) kautta. Kyselyt ovat usein laajempia sekä monimutkaisempia. |
WSDL on XML-pohjainen tiedosto, joka kertoo, mitä verkkopalvelu tekee. |
|
STANDARDIT |
REST on arkkitehtuurityyli, ei standardi. Hyödyntää HTTP-standardia. Käyttää TCP:n portteja: 443 (Hypertext Transfer Protocol Secure). Salattu yhteys. 80 (Hypertext Transfer Protocol). Salaamaton yhteys. |
Vuonna 2011, IETF / RFC 6455. WebSocket on pelkkä protokolla. Käyttää TCP:n portteja: 443 (WSS WebSocket Secure) Salattu yhteys. 80 (WS WebSocket). Salaamaton yhteys. Protokolla muistuttaa HTTP:tä paljon. |
Avoin standardi kehitteillä: (Linux Foundation, GraphQL Foundation) Hyödyntää HTTP-standardia |
WSDL-versiot: Vuonna 2000, versio 1.0. Vuonna 2001, versio 1.1. Vuonna 2007, versio 2.0. |
|
TYYPILLISET TIEDOSTOMUODOT |
JSON, XML |
Täytteenä käytetään esimerkiksi MQTT, GTFS-RT |
Oma kyselykieli (data query and manipulation language for APIs) |
XML |
|
HEIKKOUDET |
Jatkuvaa yhteyden avaamista ja sulkemista Tietomallista riippuen tiedon kysely-vastaus -ketjut voivat olla pitkiä ja tarvittavaa tietoa ei voida kysyä suoraa. Tästä näkökulmasta GraphQL on paljon tehokkaampi. Uuden tiedon tarkastusta (pooling) ei tueta |
“Pelkkä kaksisuuntainen dataputki” Sen sisältö pitää sopia erikseen. |
Kehitteillä oleva standardi. Työkalut, osaajat, tulevaisuus |
Monimutkainen Käytöstä poistuva. Ei esimerkiksi opeteta enää kouluissa. |
|
TOIMINTAPERIAATE |
Kysymys-vastaus -ketjut |
Kaksisuuntainen tietovirta |
Oma kyselykieli. Muistuttaa vähän tietokantojen SQL-kyselykieltä. |
XML-sanomia |
|
RAJAPINNAN |
Suosituimmat tavat dokumentoida ovat Open API ja YAML. Open API:n käyttö kasvaa ja YAML käyttö vähenee. |
Dokumentointi riippuu siitä, mitä selaimen ja palvelimen välille muodostettavan "tyhjän" dataputken sisällä käytetään. Jos esimerkiksi käytetään MQTT:tä, niin siitä on oma OASIS-standardi (ISO/IEC 20922). Sitä voidaan käyttää Websockettien päällä tai olla käyttämättä. Käytännössä MQTT on oma kokonaisuutensa, jota voidaan käyttää myös ilman Websocketteja. |
Osittain automaattinen.
|
Web Services Description Languagen avulla määritellään verkkopalvelu. |
| KÄYTÄNNÖN ESIMERKKI? | https://vayla.fi/vaylista/aineistot/digiroad/aineisto/rajapinnat | https://www.digitraffic.fi/meriliikenne/#mqtt-websocket--rajapinnat | https://wp.oulunliikenne.fi/avoin-data/pyorailykavely/graphql-rajapinnat/ |
Tällä hetkellä avointa dataa jakavien rajapintojen standardi Suomessa ja muualla maailmassa on RESTful-arkkitehtuurimallilla toteutetut rajapinnat, joiden markkinaosuus on eri arvioiden mukaan yli 90% kokonaisuudesta. WSDL/SOAP on poistumassa oleva tekniikka, mutta näitä rajapintoja on käytössä edelleen vanhemmissa järjestelmissä. Websocket-rajapintoja käytetään jossain erityissovelluksissa lähinnä. GraphQL käyttö lisääntyy, mutta sen käyttö on edelleen aika pientä.
Rajapinnat käsittelevät tietoa aina jollain tavalla. Verrattaessa rajapintoja datan avaamiseen tiedostoina, kasvavat sekä datan avaajan että hyödyntäjän teknisen osaamisen tarve.
Mikään rajapinnan teknologinen toteutustapa ei ratkaise tiedon semanttista yhteentoimivuutta. Semanttinen yhteentoimivuus tarkoittaa, että tiedon lähettäjä ja vastaanottaja ymmärtävät tiedon sisällön täsmälleen samalla tavalla. Käytännössä sillä tarkoitetaan, esimerkiksi sana “palkka” määritellään siten, että sen voi ymmärtää vain yhdellä tavalla.
RESTful-arkkitehtuurityyli jättää suuria vapauksia siihen, miten käytännön tasolla asiat tehdään:
- miten muuttujia ja metodeja nimetään
- mitä virheilmoituksia käytetään ja mitä ne tarkoittavat
- mitä ohjelmointikieliä käytetään rajapinnan teknisessä toteutuksessa
- miten rajapinta versioidaan ja miten sen toimintalogiikka rakennetaan (kysymys-vastaus -ketjut ja informaatioarkkitehtuuri)
- miten rajapinta dokumentoidaan (arkkitehtuuri-tyyli ei ota kantaa dokumentaatioon)
- miten rajapinnan käyttöönottoprosessi tehdään (jaetaanko esimerkiksi API-avain miten)
Edellä mainituista syistä RESTful-arkkitehtuurityyliä on täydennetty monen eri tavoin. Esimerkiksi Open API -määrittely pyrkii standardisoimaan tavan dokumentoida RESTful-arkkitehtuurityylin rajapintoja. Usein RESTful-rajapintaa on hyvin vaikeaa hyödyntää ilman dokumentaatiota. Tyypillisesti rajapintojen tyylioppaassa otetaan kantaa muuttujien ja metodien nimeämiskäytäntöihin ja virheilmoituksien käyttöön. Esimerkkinä Googlen rajapintojen tyyliopas (API design guide). Suomen julkisella hallinnolla ei ole vielä yhteistä tyyliopasta olemassa. Rajapinnan suunnittelussa ja toteuttamisessa tulee kuitenkin hyödyntää jotain yleisesti tunnettua tyyliopasta, joka ratkaisee monia laajasti tunnettuja ongelmia.
|
KÄYTÄNNÖN ESIMERKKI HYVÄSTÄ AVOINTA DATAA JAKAVASTA RAJAPINNASTA Hyvä käytännön esimerkki avointa dataa jakavasta rajapinnasta on Digitraffic (https://www.digitraffic.fi/). Vuonna 2019 sen sisältämiä tietoja kysyttiin keskimäärin 14 miljoonaa kertaa rajapinnan avulla vuorokaudessa: https://www.fintraffic.fi/fi/uutiset/digitraffic-palvelussa-jo-14-miljoonaa-rajapintakutsua-paivassa-yha-useampi-suomalainen. |
Paikkatietojen rajapinnat (WMS & WFS)
Paikkatietojen osa-alueelle on luotu omia rajapintoihin liittyviä standardeja. Aktiivisesti osa-alueella standardien luomista on edistänyt Open Geospatial Consortium (OGC) -yhdistys. Näistä käsitellään WMS ja WFS.
Web Map Service (WMS) on rajapinta paikkatiedon muodostavan kartan lataamiseen kuvina. Kuvat voivat olla eri esitysmuodossa. Esimerkiksi PNG, JPEG, GIF tai vektorigrafiikkana esimerkiksi SVG- ja WebCGM-esitysmuodoissa. WMS on standardoitu ja sen ovat julkaisseet Open Geospatial Consortium (OGC) ja International Organization for Standardization (ISO). ISO-standardi on ISO 19128:2005 (Geographic information — Web map server interface).
Web Feature Service (WFS) on rajapinta paikkatietokohteiden etsintään, kyselyyn ja muokkaamiseen. Rajapinta on OGC:n ja ISO:n standardoima.
Yhteenveto
- Avoimen datan julkaisu tulisi ajatella palveluna, tarjoomana tai tuotteena asiakkaille. Se on markkinointikanava, kuten internet-sivut, fyysinen toimipiste, puhelinpalvelu tai sähköposti. Parhaiten asia onnistuu, jos dataa avaava organisaatio käyttää itse myös avaamaansa dataa "uudestaan" omissa toiminnoissaan.
- Käytä avoimen datan rajapinnan toteuttamisessa RESTful-arkkitehtuurityyliä (tyypillisesti REST/JSON tai REST/CSV)
- Noudata jotain yleisesti tunnettua tyyliopasta (esimerkiksi Google API design guide) ja kerro avoimesti, että rajapinta noudattaa sitä
- Dokumentoi rajapinta ja tarjoa lähdekoodi-esimerkkejä sen hyödyntämiseen. Varmista hyödyntäjiltä, että rajapinnan käyttö onnistuu ja kuuntele herkällä korvalla palautetta
- Käytä rajapinnan käytön erotteluun API-avainta, jonka rekisteröitymisprosessi on automaattinen ja kerää mahdollisimman vähän henkilötietoja (usein sähköpostiosoite riittää)
- Tarjoa rajapinnalle sellainen palvelutaso (SLA), että se riittää hyödyntäjien perustarpeisiin. Kerro palvelutaso avoimesti rajapinnan dokumentaatiossa
- Suunnittele rajapinnan elinkaari etukäteen (esimerkiksi 2-3 vuotta) ja tiedota hyödyntäjiä hyvissä ajoin etukäteen muutoksista
- Varmista avattavan tiedon yhteentoimivuus määrittelemällä sen tietomalli semanttisesti esimerkiksi yhteentoimivuusalustaa hyödyntäen