okffi / open-api-definition Goto Github PK

1. Rajapinta muodostaa selkeän kokonaisuuden --> On tullut ilmi, että kuntien toimittajalukoissa on olemassa rajapintoja, joiden toiminnallisuus on niin sekavaa, että ne muodostavat käytännössä vertikaalisen toimittajalukon. Mietin, pitäisikö määritelmässä olla jotain tästä? Miten näihin tulisi puuttua.

Pitäisi olla niin, että originaalimateriaali tulisi suoraan reposta julkiselle puolelle. Nyt tein vain gh-pagesin manuaalisesti, koska en osannut.

Ainakin mulle tulee listallinen erroreita, kun menen sivustolle okffi.github.io/open-api-definition/ .

Resurssien linkit ovat väärin. Esim. modernizr.js löytyy osoitteesta http://okffi.github.io/open-api-definition/js/modernizr.js

Päivitetty selkeämmäksi 29.11

Antaessaan mahdollisuuden kuitata (ainakin?) testattavuus-vaatimuksen testijärjestelmällä, vähintäänkin hämärtyy mitä määritelmän käsitteellä "rajapinta" tarkalleenottaen tarkoitetaan. Jos kerran "rajapinta" on testattava, kun tarjotaan pääsy testijärjestelmään, alkaa testijärjestelmä kuulostaa rajapinnan osalta, "tuotantojärjestelmän" rinnalla.

Mitä on "testattavuus", joka välillä toteutuu pääsyllä tuotantojärjestelmään ja välillä testijärjestelmään? Järjestelmään tietoa tallentavan ohjelman kehittämisessä pääsy pelkästään aitoa dataa sisältävään tuotantojärjestelmään, olisi testattavuuden kannalta vähintäänkin hankalaa, sillä testit sotkisivat aitoa dataa.

Tuntuisi paremmalta ratkaisulta 1) käsitellä erikseen tuotantojärjestelmän ja testijärjestelmän rajapinnan avoimuutta ja 2) kertoa erillisen testijärjestelmän tarpeellisuudesta ja mahdollisuuksista, ilman että määritelmä itse kytkee näitä yhteen. Tämä voisi myöskin lisätä määritelmän hyödyllisyyttä hankkeiden avoimuusasteiden määrittelyssä. Voitaisiin yksiselitteisemmin esittää testiympäristön/sandboxin olevan avoin, mutta tuotantorajapinnan olevan suljetun ja vaativan esim. viranomaisen statuksen sekä sopimuksen allekirjoittamisen.

Uskoakseni testi- ja tuotantojärjetelmä ovat julkishallinnon tapauksessa usein erillisiä servereitä, sillä niiden samassa järjestelmässä (saman endpointin takana) pitäminen olisi iso riski rajapinnan onnistuneelle käyttämiselle (ettei rajapinnan käyttäjä vahingossa altistu testidatalle). Rajapinnoissa, joissa tietoavaruus on pilkottu käyttäjäkohtaisiin aliavaruuksiin, kuten GitHub:issa, oman käyttäjätunnuksen alle tallennettua dataa voi käyttää osittaiseen testaamiseen.

FB ryhmässä tuli kritiikkiä:

Määritelmä näyttää ihan kivalta. Toki tiukalta. Joka voi olla ihan hyvä asia. Mutta esimerkiksi Yle API ei tulene määritelmää täyttämään. Yle API tulee olemaan avoimesti dokumentoitu, mutta emme varmaan ihan ensimmäiseksi tule tarjoamaan automaattisia rekisteröitymisiä. Tulemme asettamaan rajapinnan käytölle joukon ehtoja (API-lisenssi), samoin kuin varmaankin myös sisällöllisiä rajoituksia.
Silti koen, että olen "avaamassa rajapintoja", vaikkei määritelmään asti yllettäisikään (tai oltaisi edes tavoittelemassa).

After new Jekyll -based site layout #13 was published, @Mygee requested adjustment to they site layout. Main document should be directly on the front page, instead of theme default (of being separately on the blog article -type of page).

Benefit would be removing extra step from the site visit user flow.

Keskustellaan näistä. Esim. Ylen edustaja (Rossi) on tuonut esille, että nämä eivät ole välttämättä kohdallaan määritelmässä.

Se preformatted-muoto ei sovi käytettäväksi tässä eikä oikeastaan missään.

Itse harkitsisin tuon "kilpaileva järjestelmä"-kohdan muuttamista imperatiiviksi. Eli että rajapinta ei ole avoin, mikäli kilpaileva järjestelmä joka on tehty eri työkaluin ei ole yhteensopiva kaikkin rajapintaa hyödyntävien sovellusten kanssa.

Voisin kuvitella että esim tavaramerkittyjä laabeleita käyttäen tai kryptografisesti varmentaen voisi tehdä avoimen rajapinnan, jota muut eivät kuitenkaan saa lakisääteisesti tarjota loppuasiakkaille. Myöskään patentoidun toiminnallisuuden avoin rajapinta ei tarkoita mitään.

Jos dokkari kestää, loisin tähän vielä vahvan avoimuuden määritelmän, eli sellaisen lupauksen siitä, että avoimuutta ei toimittaja voi yksipuolisesti myöhemmin vähentää. Eräänlainen copyleft avoimuudelle. Sillä muuten voin kuvitella että Efficaan tulee avoin rajapinta, joka ei tarkoita mitään.

Avaan nyt keskustelun määritelmän vaatimasta avoimen rajapinnan dokumentaatiosta.
Yleisesti dokumentaation puute on suurin este rajapintojen hyödyntämiseen. Esimerkiksi koodiesimerkkien puute on todellinen ongelma rajapinnan hyödyntämisessä.

Käsitteen tarkennus.

Tässä pohjaksi vanha juttuni aiheesta: http://ollintuumailut.blogspot.fi/2014/07/avoin-rajapinta-sote-uudistuksen-itn-ja.html

Tämä ratkaisee miltä sivusto näyttää FB-feedissä.

Tuolta FB:n debuggerista näkee, että kaikki ei oo kunnossa.

Logo-kuva on kovin matalaresoluutioinen.

Vaikka sivuston korjais, FB ei välttämättä (ainakaan kovinkaan pian), havaitse muutosta. Se kannattaa trigata tuolta: "Fetch new scrape information".

Nyt OKF, COSS ja API Suomi - ketä muita kannattaisi pyytää mukaan?

Keneen ja minkä foorumin kautta pitäisi olla yhteydessä, jos on jotain kysyttävää?

Haluaisin kommentteja avoimen rajapinnan määritelmään, kohtaan: "Kommentti: Rajapinnan dokumentaatiosta ja testiaineistoista ei peritä maksua, mutta palvelun varsinaiseen tietosisältöön käsiksi pääsemisestä voidaan periä myös maksu, vaikka rajapinta olisi avoin." Tämä on liian laajasti/yksisilmäisesti sanottu, mutta taustalla on käsittääkseni myös oikeita huolia. Kohdan ymmärtää helposti liian laajasti ja tähän liittyy kysymys rajapinnan ja datan avoimuuksien erosta (avoin rajapinta, suljettu data).

Miten näette avoimen rajapinnan määritelmän suhteessa seuraaviin:

• rajapinnan ollessa avoin sen testaamisen ja käyttämisen tulee olla maksutonta (tämä lienee selvää),
• tuleeko vähintäänkin jotakin sisältöä olla saatavilla myös maksuttomasti, vai voiko rajapinta olla vain teknisesti avoin (testattava, rajapinnasta itsestään ei peritä maksua, mutta kaikki tietosisältö on suljettua),
• rajapinnan ja sisällön saatavuudessa voi mielestäni olla palvelutasotyyppisiä rajoituksia, esim. hyvä palvelutaso (esim. isot kyselyvolyymit) on maksullinen, vaikka rajapinta on sinänsä avoin,
• vaikuttaako asiaan, jos osa tiedosta on avoimesti ja ilman kontrollia saatavilla ja osa tiedosta on rajattu käyttöoikeuksien taakse?

Tämä liittyy pull requestiin: https://patch-diff.githubusercontent.com/raw/okffi/open-api-definition/pull/42.patch

Tämä liittyy myös määritelmän myöhempään kohtaan, jossa sanotaan:

Avoimen rajapinnan kautta saatavan datan ei tarvitse olla avointa dataa5. Rajapinta voi olla avoin, vaikka tuotantojärjestelmä olisi kokonaan irti Internetistä ja pääsy siihen vain hyvin rajatulla joukolla. Jos rajapinta on avoin, mutta pääsy datasisältöön on rajoitettu, tarjolla tulee olla avoimesti verkossa käytettävissä oleva testiympäristö

Kommentti: Jos järjestelmään on tarjolla avoin rajapinta, se ei tarkoita, että tuotantojärjestelmään tai sen sisältämään tietoon pääsisi kuka vain käsiksi. Esimerkiksi potilastietojärjestelmään voi olla avoin rajapinta, mutta potilastiedot eivät ole avoimia. Avoimen rajapinnan kautta voidaan myös tarjota tiettyä henkilöä koskevia tietoja vain tämän omalla suostumuksella (my data).

Voidaanko pitää tällainen selkeä erottelu rajapinnan ja datan välillä? Entä mikäli erottelu on näin, tulisiko jotenkin selkeyttää sitä, miten nimitetään sellaisia avoimia rajapintoja, joissa sisältö on täysin suljettu?

Rajapinta käsittelee aina myös tiedon semanttiikaa, eli vapaasti tulkiten sitä, mitä sanoilla tarkoitetaan. Esimerkiksi ajan voi esittää / ymmärtää ainakin 20 erilaisella tavalla tietokannassa. 12/24h, päivämäärän merkintätapa jne.

Semantiikkaa ja metadataa pohtii mm. W3C:
https://www.w3.org/TR/dwbp/#context

Tässä ketjussa voi keskustella siitä, miten tiedon semanttiikka pitäisi ottaa huomioon rajapinnan määritelmässä.

Pitäiskö olla määritelmässä mukana?

Tiedän -- tätä ideaa inhoaa monet -- mutta PDF-versio voisi lisätä määritelmän käyttöä julkisessa hallinnossa "tarjouspyynnön" liitteenä. code.gov on mm. tehnyt näin.

Tässä ketjussa keskustellaan JHS-työhön vaikuttamisesta.

Pitäisi kehitellä badge avoimen rajapinnan tukijalle. Sen voisi sitten tällätä verkkoon eri paikkoihin.

FB ryhmässä tullut kommentti:

"Koska rajattomasti skaalautuvan rajapinnan toteuttaminen on työlästä ja voi maksaa paljon, niin saako avoimeksi määritelty rajapinta kuitenkin rajoittaa (throttling) esimerkiksi rekisteröitymättömien käyttäjien pyyntöjen (n pyyntöä / min) määrää joko oletusarvoisesti tai kun resurssit ovat loppumassa?

Ajattelen tässä lähinnä sellaista tilannetta, että joku tekee rajapintaa suoraan hyödyntävän, todella suosituksi yllättäen tulevan palvelun, joka rajapintaan lamauttavan ruuhkan (vrt. Slashdot effect)."

Githubissa kannattaa käyttää release ominaisuutta ja jatkaa saman tiedoston päivittämistä vanhan päälle, jolloin on mahdollista verrata saman tiedoston eri versioita (nyt ei kai toimi, kun 1.0 ja 1.1. ovat erillisissa tiedostoissa).

Loin nyt v1.0.0 tagin siihen committiin, jossa oli viimeisimpänä muokattu ykkösversion .md tiedostoa.

Takautuvasti vanhempiin kommitteihin release -tageja voi liittää tämän ohjeen mukaisesti.

Eli ehdotan, että 1.1. tekstin muutokset laitetaan vanhan päälle ja luodaan sitten 1.1. release ja vastaavasti jatkossa kohti 1.2. jatketaan päivitysten tekemistä samaan.

Pitää huolehtia, miten julkaisupuoli toimii avoinrajapinta.fi domainissa (laitetaan sinne linkit eri versioihin, joiden sisältö haetaan realease-tagien mukaisesti)

GitHub:issa on tuki osallistumisohjetiedostolle.

Tähän mennessä määritelmän päivittämistä on vasta suunniteltu GitHub-issueissa. Koska määritelmä on jo käytössä Helsingin kaupungissa ja valtiolla, on määritelmän päivittämisen oltava hallittua. Git ja GitHub tarjoavat siihen hyvät välineet, jos vaan osallistujat saadaan mukaan opettelemaan työskentelytapaa. API:Suomi-ryhmässä keskustelua prosessista.

Avaan keskustelun siitä, miten usein uusi versio määritelmästä tehdään ja miten prosessin pitäisi toimia. Taustaksi. Alkuperäisen määritelmän sisällöstä käytiin keskustelua kuukausia. Määritelmä yritettiin laatia niin, että siinä ei olisi aukkoja. Tarkoituksena oli hyödyntää määritelmää ohjelmistojen hankinnassa. Aiemmin melkein mitä tahansa rajapintaa saatettiin kutsua "avoimeksi rajapinnaksi". Viimeaikoina määritelmän käyttö on laajentunut siihen suuntaan, että sen avulla kehitetään uusia rajapintoja. Määritelmän päivittämisessä haetaan tasapainoa pysyvyyden ja kattavuuden kanssa. Lisäksi halutaan pitää ihmisen motivaatiota osallistua määritelmän tekoon ja hyödyntää määritelmää käytännössä yllä.

Määritelmän kääntäminen englanniksi. Varmaan ensin yksi versiopäivitys ja sitten.

Sivun fontit ovat todella vaikeasti luettavissa ainakin omalla koneellani. Harmaa teksti ei oikein erotu valkoisesta pohjasta. Perustekstin väri kannattaisi vaihtaa mustaksi tai miettiä koko värivalikoima uusiksi.

Tarvitaan logo avoimelle rajapinnalle.

Aika paljon on tullut kommentteja siitä, että rajapintaa pitäisi eri tavoin rajoittaa esim. palvelunestohyökkäyksessä. Avaan keskustelun tästä asiasta täällä. Kommentoikaa tähän, mitä ongelmia tähän liittyy ja ehdottakaa muutoksia rajapinnan sisältöön tähän tyyliin: "tämä teksti" kannattaisi "korvata tällä tekstillä".

Avaan keskustelun tästä aiheesta.
Tyypillisesti API managementissa hallitaan esim näitä:
http://www.developereconomics.com/api-management-tools-how-to-find-the-one-for-you/
Eli:

1. Documentation – Sounds boring, right? Still, one of the most common problems of developers is figuring out how an API works. Development time is too precious to waste in trial and error of an undocumented API. An API management service has to provide an easy way to read the documentation and enable developers to “try before they buy”. In some cases it is even possible to provide interactive documentation. Simplicity and usability are the keys!
2. Analytics and Statistics – It is critical to understand how people use your API and get insights for your business.
3. Deployment – Should be flexible and support public or private clouds, on-premises implementations, or combinations.
4. Developer engagement – Engaging with your API consumers, developer or partners is important. Getting an easily accessible developer portal will significantly facilitate onboarding.
   Sandbox environment – This feature will increase both the value of an API and its adoption rate. What better than being able to develop and test your code.
   Traffic management and caching abilities.
5. Security – APIs carry sensitive data, so it is important to protect the exposed information. The service has to at least provide identity and access management for users and developers.
6. Monetization – Provide the capability to monetize your API.
7. Availability – Should be available, scalable and redundant. An API environment can become demanding and the service should be able to deal with any kind of errors, problems or temporary traffic spikes.
8. Support of Legacy systems.

Määritelmän viimeisessä luvussa (kaksi viimeistä virkettä) on turhaa toistoa.

Alkuperäinen:
Tilaajan hallitsema rajapinta tarkoittaa rajapintaa, jota järjestelmän tilaajalla on oikeus käyttää ja levittää haluamallaan tavalla. Tällöin tilaaja voi halutessaan avata rajapinnan järjestelmäntoimittajasta riippumatta, mutta mikäli näin ei tehdä kyse ei ole avoimesta rajapinnasta. Mikäli tilaaja ei avaa rajapintaa, ei rajapinta ole ulkopuolisille avoin, jolloin kyse ei ole yleisesti ottaen avoimesta rajapinnasta.

Muutosehdotus:
Tilaajan hallitsema rajapinta tarkoittaa rajapintaa, jota järjestelmän tilaajalla on oikeus käyttää ja levittää haluamallaan tavalla. Tällöin tilaaja voi halutessaan avata rajapinnan järjestelmäntoimittajasta riippumatta. Mikäli näin ei tehdä, ei rajapinta ole ulkopuolisille avoin, jolloin kyse ei ole yleisesti ottaen avoimesta rajapinnasta.