This is a read only archive of pad.okfn.org. See the shutdown announcement for details.

• 1: LUONNOS
• 2: LINKKEJÄ JA VIITTEITÄ
• 3: KYSYMYKSIÄ JA KESKUSTELUA

• Liikkeellä on paljon  sumutusta, missä esim. järjestelmätoimittaja väittää, että  järjestelmässä on avoin rajapinta, mutta käytännössä rajapinnan dokumentaation saa vain maksamalla ja se on vain muutamille valituille  alihankkijoille.
• Avoimia rajapintoja pitäisi tarjota tarkoituksenmukaisella tasolla. Esimerkiksi arkkitehtuurissa selkeästi erilliset arkkitehtuurikomponentit pitäisi olla erillisten avointen rajapintojen takana, jos ei ole erityistä syytä toimia toisin.

• Mikäli järjestelmän  ohjelmalogiikka toteuttaa rutiinitoimintoja kuten  geokoodaus, jotka  voisivat olla hyödylisiä myös järjestelmän dataa  hyödyntäville  ulkopuolisille sovelluskehittäjille kannattaa tällaiset toiminnot  tarjota myös rajapinnan kautta käytettäväksi.

1. Dokumentoitu: Rajapinta on määritelty ja sen dokumentaatio on verkon kautta avoimesti saatavilla. Järjestelmän sisältämät tiedot, niiden rakenne ja rajapinnat tulee  dokumentoida riittävällä tarkkuudella, jotta rajapinnan käyttöönotto ja  hyödyntäminen on vaivatonta.
2. Käyttöönotettava: Avoin rajapinta on mahdollista ottaa käyttöön ilman ylläpitäjän tai järjestelmätoimittajan toimia (myös virka-ajan ulkopuolella). Mahdolliset rekisteröitymiset ym ovat automaattisia.
3. Testattava: Rajapintaa voi koekäyttää, eli tarjolla on vähintään testiaineisto.
4. Teknologia-agnostisuus: Rajapinnan pitää olla käytettävissä ja saatavilla kaikilla sen kanssa yhteensopivilla kutsu-, haku- ja päivityskäytännöillä ja -tekniikoilla käyttöjärjestelmän, alustan, protokollan tai muun teknologisen sitoumuksen estämättä.

• Henkilötietoja sisältävästä datasta voi tehdä avointa häivyttämällä  aineistosta henkilön yksilöivät tiedot. Tällöin voidaan menettää osa  datasta. Yli satavuotiaita sisältävä data voidaan joutua poistamaan  avoimesta datasta, koska heidät voi yksilöidä liian helposti iän ja  sijainnin perusteella.

• Palveluun A on rajapinta tarjolla, ja palvelun toimittaja on sitoutunut tarjoamaan sen asiakkaidensa osoittamille kolmansille osapuolille -> SULJETTU
• Palvelun B datarajapintaan pääsee vapaasti käsiksi, mutta toiminnalliseen rajapintaan ei. Rajapinta on julkisesti netissä, ja esimerkkikoodia löytyy googlella -> AVOIN, mutta vain datarajapinnan osalta
• Palveluun C on olemassa toiminnallinen rajapinta. Päästäkseen siihen käsiksi täytyy pyytää käyttöavain palvelun tarjoajalta, koska palvelu ei kestäisi vapaan käytön kuormitusta. Käytännössä lupa myönnetään aina. -> SULJETTU? Jos palvelusta tarjottaisiin testiversio vapaasti käytettäväksi, se olisi avoin
• Palveluun D on rajapinta, jonka määrittelyt ja dokumentaatio ovat vapasti saatavilla. Itse palveluun ei pääse vapaasti käsiksi, koska se sisältää ihmisten henkilötietoja. Palveluntarjoaja pitää kuitenkin yllä testipalvelinta, jossa on esimerkkidataa, ja testipalvelimeen pääsee käsiksi luomalla itselleen tunnuksen palveluntarjoajan järjestelmään. -> AVOIN

• Paremmat palvelut: Vaihtoehtoisten sovellusten ja käyttöliittymien kehittämisen helppous
• Toimittajaloukun välttäminen: Yksi tärkeä syy rajapintojen  vaatimiseen on halu välttää lukkiutuminen alkuperäiseen  järjestelmätoimittajaan. Rajapintojen avulla lisäominaisuudet voi tilata  muiltakin toimittajilta, koska järjestelmän ydin - sen tiedot - on  saatavilla rajapintojen kautta. Ilman rajapintoja on usein se tilanne,  että ainoastaan alkuperäinen järjestelmätoimittaja osaa tai pystyy  tekemään muutokset.
• Yhteensopivuus: ..
• Jatkokehittämisen helppous: järjestelmien laajentaminen ja muuttaminen on helpompaa, jos eri osat kommunikoivat toistensa kanssa hyvin määriteltyjen rajapintojen kautta.
• Arkkitehtuuri pitäisi olla avoin, ja jos mahdollista, myös sen komponenttien väliset liitännät avoimia [ estää monoliittien rakentamisen ]

• Uudet JIT ehdot määrittelevät, että ostajalla pitää olla mahdollisuus halutessaan avata rajapinta (laittaa dokumentaatio ja testiaineisto verkkoon yms.) ilman, että toimittaja puuttuu siihen. JIT-ehdot eivät kuitenkaan vaadi, että kaikissa julkishallinnon ostamissa ohjelmistoissa rajapinnat olisi pakko avata, vaan tämä jää ostajan ...? (lause jäänyt kesken?)
• Dokumentaatiossa Rajapinnan  tila on monesti hyödyllinen tieto; se elää ja muuttuu;  saattaa olla  rasittunut; osa metodeista voi olla rikki tai alhaalla  tilapäisesti;  online tilassa....

• Standardointi: Rajapintojen toteutuksessa kannattaa suosia yleisesti käytettyjä standardeja, protokollia sekä formaatteja. Käytännössä rajapinta voidaan toteuttaa esimerkiksi REST-arkkitehtuurin mukaisesti siten, että sen kautta järjestelmän tiedot saadaan koneluettavana XML-muodossa sekä selainpohjaisia sovelluksia varten JSON-muodossa. Tässä kiteytyksessä ei oteta kantaa harmonisointiin. Harmonisointi on kuitenkin looginen kehityskulku, jotta kaikki avoimet rajapinnat eivät olisi keskenään erilaisia, vaan syntyisi ainakin toimialakohtaisesti yhteisiä käytänteitä. Open311.org on hyvä esimerkki avoimien rajapintojen standardoinnista.

• Rajapinnan käyttö ilman rekisteröitymistä: Rajapinnan avoimuus ei velvoita tarjoamaan pääsyä tuotantojärjestelmään tai tuotantodataan vapaasti, vaan sen osalta voidaan vaatia esim. SLA.
• Jos itse tuotantojärjestelmään ei pääsyä, täytyy tarjota testijärjestelmä avoimesti kehittämistä varten.
• Avoimen rajapinnan kautta sallitaan ilman rekisteröitymistä tiedon lataukset, jotka eivät aiheuta järjestelmän muuta toimintaa haittaavaa    kuormitusta.

• Kuormitusrajoitukset:   Avoin rajapinta toteutettava siten, että sitä kuormittamalla ei voi (ainakaan vahingossa) aiheuttaa uhkaa tai haittaa tietojärjestelmän    muulle käytölle. Eli esimerkiksi rajapinnassa teknisesti rajattu   kutsujen määrää per aikayksikkö. Tämä saattaa aiheuttaa tarpeita kahdentaa osia tietojärjestelmästä (vrt. Reittiopas).

• Muutoshistoria ja taaksepäin yhteensopivuus: Rajapinnan yhteydessä näytetään loki rajapintaan mahdollisesti tulleista muutoksista. Tämä loki tarjotaan mielellään myös RSS-syötteenä tai sähköisenä uutiskirjeenä, jotta rajapintaa hyödyntävät toimijat saavat viipymättä tiedon rajapinnan muutoksista. Rajapinnan muutoksissa tulee pyrkiä taaksepäinyhteensopivuuteen, niin että olemassa olevat palvelut eivät mene rikki. Mikäli muutos on suuri, kannattaa rajapinta versioida; käytettävissä voi olla useita eri versioita rinnakkain. Tämä voidaan tehdä esimerkiksi sisällyttämällä rajapinnan versionumero palvelukutsun URI-polkuun. Tiedot  rajapinnan kehityksestä pitää jakaa viivytyksettä myös muille  kehittäjille, ts. jos palveluntarjoaja tekee v1.0 rajapintaan v1.1  päivityksen, se pitäisi olla ennalta tiedossa, jotta esim. muut  kaupalliset toimijat voivat sopeutua siihen ilman oman palvelun  katkosta. [ Tietysti vaatii rekisteröinnin tms. ]

• Valmisteilla olevat JIT-ehdot
• nykyiset http://www.jhs-suositukset.fi/suomi/jhs166
• Luonnos "avoin data vaatimusmäärittelyissä" http://muistio.tieke.fi/avoindata-vaatimukset
• Open AOI manifesto https://github.com/JonBou/open-API-manifesto/wiki/Manifesto-version-0
• opendefinition http://opendefinition.org/

• Voidaanko toiminnallisille rajapinnoille antaa vähän släkkiä?
• Käytännössähän siis jos on toiminnallinen rajapinta, jonka kautta pääsee käsiksi ei-julkisiin tietoihin, niin sen tekeminen avoimeksi edellyttäisi paitsi esimerkkiaineistoa, niin myös jotain hiekkalaatikko testiserveriä tai vähintään hyvin dokumentoitua ladattavaa testiympäristöä (joku virtual box), jonka kehittäjä voisi ladata ja ajaa omalla komeellaan. Voidaanko / kannattaako tällaista edellyttää vai voidaanko sanoa, että on ihan ok, jos toiminnallista rajapintaa pääsee testaamaan pyynnöstä?
• Hiekkalaatikon voi välttää, jos rajapinnat antavat jonkun kiinteän mock-datan tietyillä testitunnuksilla. Esimerkiksi postin rajapintoja voi testata suoraan. Joku eKirje tai vastaava toimi siten, että tunnuksella "testitunnus" (tai vastaava) tehdyt pyynnöt tai toiminnot antoivat vastaukseksi jonkun standardiviestin. Samalla tunnuksella pystyi testaamaan kaikkien rajapintakutsujen toiminnan. Tuotantoon ottaminen vaati postin / Itellan kanssa sopimuksen. Sopimuksen mukana tuli tunnus, jolla pystyi ajamaan kutsut oikeasti.

• saako vaatia ennakkorekisteröitymistä rajapinnan käytäjäksi?
• saa vaatia, mutta hyväksynnän pitää olla automaattinen ja viiveetön? Entä jos ennakkorekisteröintiä ei pitäisi perusteetta vaatia, vaan rekisteröinti. Rekisteröinti on myös toisen osapuolen etu, ts. tiedetään ketkä sitä käyttää / kenellä on intressi, jotta voidaan (jos halua on) antaa heidän vaikuttaa kehitykseen, jne.
• Toisaalta rekisteröinnin kautta voi saada esim. oman API-avaimen, jota kautta pääsee käyttämään henkilökohtaista kuormitusquotaa, ja toisaalta saa paremmin tietoa ennalta API:in liittyvistä asioista ja suunnitelmista?
• Ennakkorekisteröinti tai tieto, että vapaalla tunnuksella tehtyihin kutsuihin liittyy esimerkiksi heikko vasteaika.

• Voiko itse palveluun integroitumisesta periä maksua, jos testijärjestelmä on vapaasti käytettävissä?
• Keskeinen kysymys lienee: Mitä kaikkea vapaa rajapinta kattaa? Yhdellä avoimella karttapalvelulla palvelimet kaatuivat, kun kaupallinen osapuoli otti heidän karttansa käyttöön. Yritys lanseerasi tuotteen, jolle he löysivät tarpeeksi käyttäjiä. Avoimen rajapinnan kautta tuli yllättäen liikaa kutsuja. Koska rajapinta ja kartan käyttö oli vapaata syntyi ongelmia.
• Miten voidaan määritellä kuinka suuri määrä käyttämistä vaatii maksun perimisen?
• Mitä, jos rajapintaa käytetään kännykän appsien kautta? Kuinka löydetään taho, joka kyykyttää rajapinnan kautta palvelimet?
• Pitäisikö tässä hahmotella esim. 3 eri "compliancy" tasoa, esim: 
• (1) Speksit (ja testidata) avoimia, mutta rajapintojen käyttäminen vaatii sopimuksen (perusteltua esim. potilastietojärjestelmissä?). Olisiko oikea termi tälle "julkinen rajapinta"?
• (2) Speksit (ja testidata) ja itse rajapinta ovat avoimia; vapaa ja riippumaton rajapintojen käyttö (mihin tarkoituksiin?) on mahdollista
• (3) Tarjotaan palvelut kolmansien osapuolten integroinnille (speksit, testidata, testirajapinnat, kaupalliset rajapinnat, mahd. click-through lisenssit, sovelluskehityksen tuki, ..) 

• Minua näissä pohdinnoissa hieman epäilyttää idealistinen "kiva avata rajapintoja" pohdinta, vs. sitten ihan kaupallinen hyödyntäminen. 
• Kaupallisessa hyödyntämisessä on se vaara, että julkisille organisaatioille tai heidän palveluntarjoajilleen muodostuu sellaisia vastuita, jotka eivät ole perusteltavissa alkuperäisen tarpeen kautta. Ts. kuinka paljon rajapinnan käyttöä pitää biffata alkuperäisen diilin sisällä, vai kuka sen maksaa? (jos siis puhutaan vaikka ihan hostauksen ja sen skaalauksen hinnasta)
• Pistin kommentin jo määrittelyyn, mutta minusta julkisuus ja maksuttomuus voisi koskea määritelmällisesti teknistä rajapintaa, mutta ei välttämättä sen toteutuksen instanssia. Avoin rajapinta ei saisi missään nimessä rajoittua ideologikseksi kaikki ilmaiseksi ja julkiseksi toteutukseksi. Rajapinta sinänsä julkiseksi ja ilmaiseksi, mutta implementaation pitäisi saada olla myös salainen ja maksullinen. Sitten jää implementoijan päätettäväksi, että millä laajuudella ja ominaisuuksilla avaa implementaatiota julkiseksi ja millä hinnalla. Mahdollisuus toki julkiseen ja ilmaiseenkin, koska rajapinnoista ei tarvitse maksaa mitään lisenssejäkään ulkopuolisille.