Return to site

Miksi APIt kannattaa luokitella?

eli miksi loimme API-tikkataulun...

· Sisäinen API,API suunnittelu,Kumppani API,Julkinen API,Avoin API

Kun alat suunnitella uutta APIa, sinun pitäisi aina kysyä itseltäsi: “kenelle suunnittelen sitä?” Tämä johtaa tietoliikenneratkaisuihin ja turvallisuusvaatimuksiin, jotka APIn pitää täyttää. Ja viimein on kysymys siitä, että kuka omistaa käsiteltävän datan ja muut APIn käyttämät resurssit.

Näitä valintoja on helpompi tehdä, jos voit jollain tavalla kategorisoida APIsi. Käytä yleisiä malleja. Monet maailman API-gurut ovat keskustelleet siitä, kuinka APIt tulisi luokitella. Esimerkiksi Kin Lane tekee eron sisäisten ja yksityisten APIen välillä1.. RestCase -blogin kirjoittaja käyttää luokitusta sisäinen, kumppani ja julkinen2. Kokemuksemme perusteella Kin Lane, jota Steve Wilmotin teoria myös tukee, on enemmän oikeassa3.

Auttaaksemme muita API-arkkitehtejämme, loimme Jarkko Moilasen kanssa API-luokitusta auttavan “tikkataulun”. Se vertaa avoimen APIn, avoimen datan APIn, sisäisen, yksityisen, kumppani ja julkisen APIn käsitteitä.

API category cheat sheet: Marjukka Niinioja & Jarkko Moilanen, 2018

API-talous 101-kirjaa kirjoittaessamme huomasimme, että APIin liittyvät käsitteet eivät olleet selkeitä. Sekä tieteellisessä tutkimuksessa että alan blogeissa käsitteitä ei määritelty kunnolla. Tilanne oli jopa huonompi käännettäessä käsitteitä ja ajatuksia muille kielille, tai kun käyttäjänä oli julkinen sektori, pääasiassa APIen ja avoimen datan yhteydessä.

Kuinka avoin on Avoin API?

Ongelmat alkavat siitä, kun käytetään käsitteitä kuten avoin API. Ihmiset olettavat, että “avoin” tarkoittaa samaa kuin 100% turvaton ja ilmainen. Avoimen APIn ja avoimen datan käsitteet ja merkitykset ovat sekoittuneet keskenään. Jotkut avoimet APIt ovat julkisesti kaikkien käytettävissä (tai rekisteröitävissä käytettäviksi). Osa saattaa tarjota avointa dataa (Open Data), toisin sanoen Creative Commons -lisensoitua (CC0) dataa tai muita vastaavia lisenssejä. Avointa dataa voidaan käsitellä muutenkin kuin REST APIen avulla, mutta kaikki APIt eivät ole avoimia rajapintoja ja suurin osa avointen APIen tarjoajista vaatii käyttäjiltä rekisteröitymistä.

Käsite alettiin ottaa vähitellen käyttöön vuonna 1996. Yksi ensimmäisistä, joka sitä käytti, oli Sun Microsystems kuvatakseen Java-laajennusten rajapintoja4. APIt olivat “julkaistuja, yhdenmukaisia, avoimia, joiden avulla kaikki voivat toteuttaa ja rakentaa”. Myöhemmin käsite muokkautui ja liitettiin REST APIin. Linux-Säätiön Open API käyttää käsitteen Open API määritelmää kuvatakseen REST APIa. Hieman hämmentävästi määritelmää voidaan käyttää myös sisäisten APIen suunnitteluun.

Julkiset ja kumppani-APIt

Olemme konsultoineet ja työskennelleet sekä julkisen että yksityisen sektorin yrityksissä, pienissä ja suurissa. Kirjoittaessamme API-talous kirjaa vertailimme muistiinpanoja ja keskustelimme Facebook-yhteisömme kanssa. Meille selvisi, että käsitteiden määrittely alussa on ratkaisevan tärkeää. Esimerkiksi, jos yleisö on pääasiassaa julkiselta sektorilta, he saattaisivat sekoittaa julkiset APIt ja julkisen sektorin tarjoamat APIt toisiinsa. Yrityksiä saattaa pelottaa lanseerata APIa, koska he olettavat, että kaiken tarvitsee olla julkista ja vapaata.

Olemme käyttäneet määritelmää, joka vaikuttaa yleisimmältä: Avoin API on joko julkinen tai Kumppani-API ja joka on tarkoitettu käytettäväksi ulkoisten osapuolten (määrittelemien) ehtojen mukaisesti.Kuten avoimet APIt Java-alustalla, nämä avoimet REST APIt on suunniteltu niin, että muut voivat käyttää niitä uudelleen ja laajentaa niiden toiminnallisuutta. API hyödyntäjät voivat rakentaa uusia palveluita käyttämällä näitä avoimia apeja. Suurin ero julkisen ja kumppani-APIn välillä on niiden käyttäjissä: Julkisia rajapintoja voi käyttää kuka tahansa ilman liiketoimintasuhdetta APIn tarjoavan organisaation kanssa. Kumppani-APIt ovat saatavilla vasta, kun käyttäjä on hyväksynyt yhteistyö- tai asiakkuussopimuksen, tai ostanut tuotteen tai palvelun.

Sisäiset ja yksityiset APIt

Sisäinen API ei ole julkisesti saatavilla ja sen käyttö on täysin ilmaista. Sisäisellä APIlla voi olla tiukka tunnistus- ja pääsynhallintakäytäntö jopa sisäiselle käytölle. Ikävä kyllä, sisäiset APIt ovat yleensä heikosti suojattuja. Ainoa suojaus on yleensä pääsy sisäiseen verkkoon tai useiden käyttäjien jakama yksinkertainen API-avain.

Sisäisissä Apeissa data ja muut tietolähteet eroavat usein ulkoisista rajapinnoista. Tuote-API saattaa olla API joka tarjoaa tuotteen perustiedot, kuten GTIN/EAN -koodit, tuotteiden nimet ja ominaisuudet. Sisäinen API voi sisältää voittomarginaalin tai varastointikoodit. Tietoa, jota ei välttämättä haluta jakaa asiakkaiden, kumppaneiden, eikä varsinkaan kilpailijoiden kanssa.

Ainakin suurimmalla osalla sisäisiä rajapintoja tulisi olla selkeät tietomallit ja samantasoinen tietoturva, kuin jos ne olisivat avoimia rajapintoja. Ne pitäisi myös dokumentoida niin, että ne on mahdollista muuttaa avoimiksi jossain vaiheessa, mutta ne parantavat sisäistä käyttäjäkokemusta tälläkin hetkellä. Julkisen APIn tasoista tietoturvaa pitäisi käyttää yksityisissäkin rajapinnoissa siksi, että niitä käytetään julkisen verkon kautta, esimerkiksi mobiilisovelluksilla. Kin Lane luokittelee nämä APIt yksityisiksi. Rest Case -blogi luokittelee sekä mobiilisovellus-APIt sekä sisäverkkojen APIt samaan luokkaan, sisäisiin. Koska pilvi- ja SaaS -palveluita on joka tapauksessa niin paljon, sisäisen verkon käsite on usein hämärtynyt. Joten yhden luokituksen käyttö soveltuu useimmille yrityksille. Me laitoimme yksityiset ja sisäiset APIt samaan luokkaan.

Isoille yrityksille on tavallista, että heillä on paljon rajapintoja, joita ei ole mahdollista altistaa ulkoisille verkoille. Yleensä syynä ovat suositukset, joko juridiset tai yrityksen käytäntö. Tavallinen esimerkki on myös julkisten organisaatioiden APIt, jotka käsittelevät salaista tai arkaluontoista tietoa. Sisäiset APIt saattavat olla myös sisäisten sovellusten tarjoamia. Niillä saattaa olla kaupalliseen käyttöön perustuva lisensointi, ei kovin käyttäjäystävällinen loppukäyttäjäsuunnittelu, heikko palvelutasosopimus (SLA, service level agreement) ja mitoitettavuus nykyistä suuremmille käyttäjäryhmille. Näitä rajapintoja pitäisi käsitellä sisäisinä, vaikka järjestelmä toimisi julkisessa pilvessä.

Lisää aiheesta API-talous 101 -kirjan luvuissa 7-9, tässä blogissa esitetty "tikkataulu" perustuu luvussa 5 sivulla 58 esitettyyn taulukkoon.

Lähdeviitteet

[1] http://apievangelist.com/2015/02/03/in-the-future-there-will-be-no-public-vs-private-apis/ (Referenced on May 13th, 2018)

[2] http://blog.restcase.com/internal-vs-external-apis/ (Referenced on May 13th, 2018

[3] https://www.3scale.net/2015/02/public-vs-private-vs-internal-apis/(Referenced on May 13th, 2018

[4] Kramer, D. (1996). The java platform. White Paper, Sun Microsystems, Mountain View, CA.

All Posts
×

Almost done…

We just sent you an email. Please click the link in the email to confirm your subscription!

OKSubscriptions powered by Strikingly