Miksi ohjelmointirajapinnat eli APIt kannattaa luokitella?

Kun alat suunnitella uutta APIa, kysy aina ensin: "Kenelle tätä suunnitellaan?" Tämän avulla määräytyy verkkorakenne ja suojaustoimenpiteet joihin APIn pitää soveltua. Ja lopuksi on kysymys siitä, kuka omistaa APIn käsittelemät tiedot ja muut resurssit.

Nämä päätökset on hieman helpompi tehdä, jos voit luokitella APIn jotenkin. Käytä yleisiä kuvioita. Monet API-asiantuntijat maailmassa ovat keskustelleet siitä, miten ohjelmointirajapinnat tulisi luokitella. Esimerkiksi Kin Lane tekee eron sisäisten ja yksityisten ohjelmointirajapintojen välillä. RestCase -blogin tekijä käyttää luokkia sisäinen, kumppani ja julkinen. Kokemuksesta meidän on sanottava, että Kin Lane on oikeastaan enemmän oikeassa.

Auttaaksemme muita API-arkkitehteja, Jarkko Moilanen ja minä loimme API kategoria-lunttilapun. Lunttilappu vertaa avoimen APIn, avoimen datan APIn, sisäisen, yksityisen, kumppanin ja julkisen APIn käsitteitä.

Kirjoittaessamme kirjaa API taloudesta aloimme nähdä, että ohjelmointirajapintoihin liittyvät termit eivät olleet selkeitä. Tieteellisen tutkimuksen ja teollisuuden blogeissa termejä käytettiin täsmentämättä niitä oikein. Tilanne oli vielä pahempi, kun termejä ja ideoita muunnettiin muille kielille. Tai kun sitä käytetään julkisella sektorilla, pääasiassa APIen ja avoimen datan yhteydessä.

Kuinka avoin Open API on?

Ongelmat alkavat, kun käytetään termejä, kuten Open API. Ihmiset olettavat, että termi "avoin" on synonyymi 100% suojaamattomalle ja vapaalle. Avoimen APIn ja avoimen datan ehdot ja aloitteet on sekoitettu keskenään. Jotkin avoimet ohjelmointirajapinnat ovat julkisia kenen tahansa käytettäväksi (tai rekisteröitäväksi käytettäväksi). Jotkut saattavat palvella avointa dataa eli Creative Commonsin (CC0) lisensoitua dataa tai muita tällaisia lisenssejä. Avointa dataa voidaan käsitellä myös muilla menetelmillä kuin REST-ohjelmointirajapinnoilla. Kaikki APIt eivät kuitenkaan ole avoimia ohjelmointirajapintoja, ja useimmat avoimen APIn tarjoajat tarvitsevat API-kuluttajia rekisteröityäkseen.

Yksi ensimmäisistä tilaisuuksista, jolloin termiä käytettiin, oli vuonna 1996. Sun Microsystems käytti sitä kuvaamaan Java-laajennusten ohjelmointirajapintoja. Ohjelmointirajapinnat olivat "julkaistuja, yhtenäisiä, avoimia ohjelmointirajapinnan rajapinnan, jonka avulla kuka tahansa voi toteuttaa ja rakentaa laajennuksen". Termiä mukautettiin myöhemmin ja se liitettiin REST-ohjelmointirajapinnoituksiin. Linux Foundation Open API -aloitteessa käytetään termiä Open API -määritys REST-ohjelmointirajapintojen kuvaamiseen. Hämmentävästi spesifikaatiota voidaan käyttää myös sisäisten ohjelmointirajapintojen suunnitteluun.

Julkiset APIt ja kumppanien APIt

Olemme konsultoineet ja työskennelleet sekä julkisen että yksityisen sektorin yrityksissä, niin suurissa kuin pienissäkin. API-talous 101-kirjaa kirjoittaessamme vertailimme muistiinpanoja ja keskustelimme Facebook-yhteisömme kanssa. Huomasimme, että terminologian määrittely on alussa ratkaisevan tärkeää. Jos yleisö oli esimerkiksi pääasiassa julkiselta sektorilta, se sekoitti julkisen ohjelmointirajapinnan julkisen sektorin tarjoamien ohjelmointirajapintojen kanssa. Yritykset eivät uskaltaneet käynnistää API rajapintoja, koska he luulivat että kaiken on oltava julkista ja ilmaista.

Olemme käyttäneet määritelmää, joka näyttää olevan yleisin: Open API on joko julkinen tai kumppani API. API, jota on tarkoitus käyttää ulkopuolisten osapuolten käyttöehtojen mukaan.

Kuten java-alustan avoimet ohjelmointirajapinnat, nämä avoimet REST-ohjelmointirajapinnat on suunniteltu siten, että muut voivat käyttää ja laajentaa toimintojaan. API-hyödyntäjät voivat rakentaa uusia palveluita käyttämällä näitä avoimia ohjelmointirajapintoja. Suurin ero julkisen ja kumppanin APIn välillä on se, kuka saa käyttää sitä. Kuka tahansa voi käyttää julkisia ohjelmointirajapinnan liittyen API-palveluntarjoajan organisaatioon ilman liikesuhdetta. Kumppanien ohjelmointirajapinnat ovat käytettävissä, kun olet hyväksynyt kumppani- tai asiakassopimuksen tai ostanut palvelun tai tuotteen.

Sisäiset ja yksityiset APIt

Sisäinen API ei ole julkisesti saatavilla, eikä sen käyttö maksa mitään. Sisäisellä API-liittymällä voi olla tiukka henkilöllisyyden ja pääsyn hallintakäytäntö myös sisäistä pääsyä varten. Valitettavasti sisäiset APIt ovat yleensä erittäin huonosti suojattuja. Ainoa suojaus on usein pääsy itse sisäiseen verkkoon tai monien jakamalla yksinkertaisella API-avaimella.

Sisäisissä API rajapinnoissa tiedot ja muut resurssit eroavat usein ulkoisista. API-tuote voi olla API, joka sisältää tuotteen perustiedot, kuten GTIN/ EAN-koodit, tuotenimet ja ominaisuudet. Sisäinen API voi sisältää voittomarginaalin tai tallennuskoodit. Tiedot eivät ole välttämättömiä asiakkaille, kumppaneille ja erityisesti kilpailijoille.

Ainakin useimmilla sisäisillä API rajapinnoilla pitäisi olla selkeät tietomallit ja tietoturva ikään kuin ne olisivat avoimia API-liittymiä. Ne tulisi myös dokumentoida siten, että on mahdollista, että APIt avataan jonain päivänä. Julkisiin ohjelmointirajapinnan tietoturvaan soveltuvuuden syynä on se, että yksityisiä ohjelmointirajapinnan käyttäjiä käytetään julkisessa internetissä, esimerkiksi mobiilisovelluksissa. Kin Lane asettaa nämä ohjelmointirajapinnat yksityiseen API-luokkaan. Rest Case -blogi asettaa sekä mobiilisovelluksen ohjelmointirajapinnat että sisäisessä verkossa käytettävät ohjelmointirajapinnat samaan luokkaan, sisäiseen luokkaan. Koska pilvi- ja SaaS-toteutuksia on muutenkin niin paljon, sisäisen verkon käsite hämärtyy usein. Joten yhden luokan käyttö voi sopia monille yrityksille. Laitoimme sekä yksityiset että sisäiset ohjelmointirajapinnat samaan luokkaan.

On normaalia, että suurilla yrityksillä on paljon ohjelmointirajapintoja, joita ei ole mahdollista vata ulkoisiin verkkoihin. Syynä on yleensä vaatimusten noudattaminen, joko lain tai yrityksen toimintapolitiikan mukaan. Tyypillinen esimerkki ovat myös salaisia tai arkaluontoisia tietoja käsittelevät julkisten organisaatioiden ohjelmointirajapinnat. Toinen tapaus on, että sisäiset ohjelmointirajapinnat saattavat olla sisäisessä käytössä olevien sovellusten tarjoamia. Niillä voi olla kaupallinen käyttäjäpohjainen lisensointi, ei kovinkaan käyttäjäystävällisiä API-kutsuja ja huonosti soveltuvat palvelulupaukset ja skaalautuvuus suuremmille kohderyhmille. Näitä ohjelmointirajapintoja olisi käsiteltävä sisäisinä, vaikka järjestelmät olisivat käynnissä julkisissa pilvissä.

Viittaukset:

[1] http://apievangelist.com/2015/02/03/in-the-future-there-will-be-no-public-vs-private-apis/ (Viitattu 13.5.2018)

[2] http://blog.restcase.com/internal-vs-external-apis/ (Viitattu 13.5.2018

[3] https://www.3scale.net/2015/02/public-vs-private-vs-internal-apis/(Viitattu 13.5.2018

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

Kun kirjoitimme kirjaa API-taloudesta, aloimme nähdä, että sovellusliittymiin liittyvät termit eivät olleet selkeitä. Tieteellisessä tutkimuksessa ja teollisuuden blogeissa termejä käytettiin määrittelemättä niitä oikein. Tilanne oli vielä pahempi, kun termejä ja ideoita käännettiin muille kielille. Tai kun julkinen sektori käyttää, lähinnä sovellusliittymien ja avoimen datan kontekstissa.