REST rajapintojen standardointi tyylioppaan avulla - 6 hyötynäkökulmaa

Updated: Jun 15, 2018

API -tyyliopas on luonnollisesti tärkeä yrityksille, joilla on useita rajapintoja ja niitä suunnittelee sekä toteuttaa useammat ihmiset. Kuitenkin yritys, jolla on jo muutama rajapinta, hyötyy merkittävästi tuottamalla edes perusasiat standardoivan API -tyylioppaan. Mitä ne perusasiat ovat, käsitellään alla. APIt ja alustat kulkevat käsi kädessä ja siksi API -tyyliopas on olennainen osa myös alustojen kehittämistä ja ylläpitoa. Artikkelissa avataan API -tyylioppaan hyötyjä kuudesta eri näkökulmasta.



Mikä on API -tyyliopas?


Englanninkielessä esiintyy tämän asian yhteydessä termejä kuten “API Style Guide”, “API Design Guide” ja “API Guidelines”. Rakkaalla lapsella on monta nimeä, mutta kyse on samasta asiasta. Tunnetuilla suurilla ja pienillä yrityksillä on omat API -tyylioppaansa.


Tyyliopas ei ota kantaa käytettyyn ohjelmointikieleen, vaan antaa reunaehtoja muotoilulle ja toteutukselle vähän samaan tapaan kuin graafiset ohjeistot yrityksen logon käytöstä. Yhtä lailla yleisesti käytetty Open API spesifikaatio luo kehikon API:n kuvaukselle, mutta jättää yksityiskohdat kuten esimerkiksi virheenkäsittely ja parametrien nimeämiskäytännöt soveltajan vastuulle. Tunnetusti paholainen asustaa juuri yksityiskohdissa. Lyhyesti sanottuna, API -tyyliopas on keino standardoida APIen suunnittelua, kehittämistä ja käyttäytymistä.(3)


API -tyylioppaita ei juuri ole akateemisesti tutkittu. Vuodelta 2017 löytyy tutkimus(2), jossa on analysoitu 32 API -tyyliopasta. Analyysissä löytyi 27 kategoriaa asioista, joita oppaat sisältävät. Viisi kategoriaa nousi esiin suurimmassa osassa analysoituja API -tyylioppaita:

  1. Versiointi (Versioning)

  2. Nimeäminen (Naming)

  3. Vastausformaatti/rakenne (Response Structure/Format)

  4. Metodit (Standard Methods)

  5. Tilakoodit (Status Codes)

Kannattaa tutustua olemassa oleviin oppaisiin, mutta ei välttämättä kopioida niitä suoraan sellaisenaan omaan käyttöön, koska monesti oppaat sisältävät myös organisaatiokohtaisia nyansseja. Tarkastellaan seuraavaksi suppeasti API -tyylioppaan hyötynäkökulmia, joita tähän on valittu 6 kappaletta.


1. Arkkitehtuurin näkökulmasta


REST ei ole standardi vaan Roy Fieldingin alkuunlaittama arkkitehtuurityyli (1). Toisin sanoen vapausasteita tehdä eri asiat on niin monta kuin API kehittäjiä. Tästä syystä API -tyylioppaalla pidetään huoli arkkitehtuurin APIen yhtenäisyydestä.


Liiketoimintasuunnitelman ja -tavoitteiden tulee ohjata arkkitehtuuria

Arkkitehtuuriratkaisut ohjaavat sitä, millaista koodia ja palveluja loppujen lopuksi tehdään. API -tyylioppaan avulla ohjataan käytännössä myös arkkitehtuurin toteutusta. Mikäli tyyliopas määrittää epäsuorasti että yrityksessä on vain datarajapintoja, on vaikea tehdä liiketoimintasuunnitelmia toiminnallisten ja tapahtumapohjaisten rajapintojen varaan.


Liiketoiminta ei saakaan olla alisteinen arkkitehtuurille, niin kuin se nykyään vielä tuntuu olevan. IT -osasto tekee rajapinnat ja liiketoimintajohto yrittää käyttää ratkaisuja osana liiketoimintaa. Liiketoimintasuunnitelman ja -tavoitteiden tulee ohjata arkkitehtuuria. Tämä puolestaan vaatii tiivistä dialogia liiketoimintajohton ja IT -osaston välillä. Niin kauan kuin nämä kaksi ihmisjoukkoa ovat kaukana toisistaan, ei tulos voi olla optimaalinen.


Mikäli yritys käyttää mikropalveluarkkitehtuuria, ovat APIt joka puolella arkkitehtuuria. Siinä vaiheessa API -tyyliopas on kultaakin kalliimpi ja keskeinen osa arkkitehtuurin toteutuksen ohjausta.


On syytä mainita, että mikropalveluarkkitehtuurissa kaikki APIt eivät monestikaan ole REST rajapintoja (vaikka voisi olla). Sisäiset rajapinnat ovat tehokkuusvaatimuksiensa vuoksi ehkä toteutettu muilla tekniikoilla kuten esimerkiksi gRPC teknologialla. Esimerkiksi Google käyttää gRPC rajapintoja paljon ja heidän API -tyylioppaansa sisältää ohjeistuksen myös niiden tuottamiseen. Näin ollen API -tyyliopas ei ole vain REST rajapintojen standardointiin, vaikka niin joskus ajatellaankin.


Sen sijaan hyvin yleisesti asiakkaan suuntaan paljastetut rajapinnat usein ovat nykyään REST tai RESTful. Riippumatta siitä, onko kyseessä sisäiset tai avoimet rajapinnat, on API -tyylioppaalla standardoiva vaikutus organisaation sisällä. APIen lajityyppeihin voit tutustua aiemman artikkelin avulla.


2. Liiketoiminnan näkökulmasta


Ilman API -tyylioppaan standardoivaa vaikutusta jokainen API on yksilöllinen, saattaa sisältää toteuttajan omia mieltymyksiä tai käytäntöjä. Kun kaavaan lisätään useampi APIen suunnittelija ja koodaaja, syntyy epäyhdenmukainen kokonaisuus.


Mielikuvat, joita epäyhdenmukaisesta API-perheestä syntyvät ovat:

  1. harrastelijamaisuus,

  2. epäluottamus,

  3. vaikea käyttöönotto (jokaisen APIn kohdalla kaikki opeteltava uudestaan) ja

  4. välinpitämättömyys.


Sanomattakin on selvää, että kaupallistetun avoimen APIn kohdalla huono kehittäjäkokemus ja "hankalan" maine on yhtä kuin menetetty tulo. Huono APIen maine ja käyttäjäkokemus pahimmillaan aiheuttaa tuhoa koko yrityksen brändille, koska asiat ja mielipiteet leviävät verkostoissa ja sosiaalisessa mediassa nopeasti. Huonon mielikuvan muuttaminen positiiviseksi ei tapahdu yhtä helposti tai nopeasti eikä varmasti pienillä resursseilla.


kaupallistetun avoimen APIn kohdalla huono kehittäjäkokemus ja "hankalan" maine on yhtä kuin menetetty tulo.

Kumppani-APIen kohdalla menetetty tulo voi olla sama tai jopa rajumpi, vaikka itse rajapinnasta ei otetakaan maksua. Sen sijaan voidaan menettää kumppanuuden kautta syntyviä tuloja, koska API on kovinkin normaaleista hyviksi havaituista käytännöistä poikkeava. Uniikki API saattaa kyllä jäädä mieleen, mutta jos sen käyttöönotto on raskasta ja epäintuitiivista, voi potentiaalinen liiketoimintakumppani etsiä vaihtoehtoisen API- tarjoajan. Korostan kuitenkin, että tyyliopas ei ole oikotie hyvään kehittäjäkokemukseen, joka on APIn menestymisen kannalta merkittävin tekijä. APIn "tuntuma" syntyy kokonaisuudesta, APIn ympärille rakennetusta tuesta, toisiaan tukevista toiminnoista ja dokumentaatiosta.


3. APIen suunnittelijoiden näkökulmasta


API -tyyliopas liittyy luonnollisesti myös API muotoiluun (design). Yhä useammin API muotoillaan ensin ja vasta sitten toteutetaan. Jotta ymmärtää APIn suunnittelijan työtä tuleee ymmärtää konteksti jossa työ tapahtuu. Alla yksinkertainen minimalistinen illustraatio kontekstista.



APIn kautta tarjotaan jonkun taustalla olevan järjestelmän resursseja käyttöön (vasemmalla). Käyttäjä on sovelluskehittäjä, joka tuottaa applikaation. Sovelluskehitäjä voi on oman talon sisältä, kumppaniyrityksen koodaaja tai ennalta tuntematon sovelluskehittäjä. Syntyvällä applikaatiolla on monesti (ihmis)käyttäjä (ei kuvassa), jonka tarpeita on myös monesti hyvä ymmärtää. Kuvassa mustalla reunuksella rajattu alue on API -tyylioppaalla standardoitavaa aluetta. Alue ulottuu HTTPn päälle kohti hyödyntävää applikaatiota koska muun muassa tilakoodit (status codes) hyödyntävät HTTP -protokollaa ja muita standardeja (määritelty API -tyylioppaassa).


APIn suunnittelijan tulee siis:

  • Ymmärtää tarpeeksi taustasovelluksesta, jotta voi tehdä viisaita päätöksiä mitä toimintoja ja dataa voi sekä kannattaa hyödyntää, miten avaaminen kannattaa tehdä ja mitä toimintoja jätetään pois.

  • Mallintaa APIn tarjoamat resurssit ja toiminnallisuus, jotka vastaavat sovelluksien tarpeita. Pahin moka on tuupata taustasovelluksen tietomalli sellaisenaan rajapinnan kautta ulos. Tässä kohdin API -tyyliopas ohjaa suunnittelijan työtä.

Mikäli yrityksessä on useampia rajapintoja, jotka muodostavat API -perheen, on API -tyyliopas suunnittelutyötä nopeuttava, koska monet toiminnot ja toimintatavat on standardoitu eikä tule houkutusta keksiä pyörää uudestaan, kiistellä loputtomasti ikuisista kiistakysymyksistä (kuten esimerkiksi CamelCase tai snake_case) tai keksiä stetsonista erinäisiä asioita. API Stylebook kokoelman luojan Arnaud Lauret sanoin:


With guidelines, API designers can focus on what really matters instead of losing time discussing endlessly about tiny details or trying to solve design problems that already have been solved within the company. (Arnaud Lauret)

APIa suunnitellessa tulee mieleen kysymys onko tekemäni design organisaation API -tyylioppaan mukainen? Tarkistuksen voi tehdä manuaalisesti itse tai antaa toisten tiimin jäsenten tehdä tarkistus kuten Googlella on tehty (4). Toinen vaihtoehto on käyttää työkalua tarkistukseen. Zalando on tehnyt avoimen lähdekoodin työkalun “Zally” APIn tyylin tarkistukseen. Zally tarkistaa onko API Zalandon RESTful tyylioppaan mukainen. Ihmiskeskeisellä review prosessilla on etunsa, mutta se vie vastaavasti enemmän aikaa sekä kuluttaa enemmän resursseja. Ohjelmallinen tarkistus tuskin pystyy vielä piakkoin tekemään ns sanity checkiä eli tarkistamaan ymmärtääkö joku muu kuin kirjoittajat niitä.

Mikäli yritys on päättänyt käyttää esimerkiksi OpenAPI speksiä APIen koneluettavaa kuvaamiseen (kuten Zalando), on tyylin validoinnin ohella tekninen validointi myös yhtä tärkeää. Mikään ei tuskastuta APIa hyödyntävää sovelluskehittäjää kuin rikkinäinen kuvaus, koska toisinaan hyödyntäjä replikoi APIsi omaan ympäristöön kehittämisen ajaksi juuri mainitun koneluettavan kuvauksen avulla.


4. APIen toteuttajan ja ylläpitäjän näkökulmasta


Yhtenäiset APIt helpottavat ja nopeuttavat koodin ylläpitoa. APIn päivitys ja bugien korjaaminen nopeutuu ja on mielekkäämpää selkeiden linjojen vuoksi. Toteuttajan näkökulmasta joka asiaa ei tarvitse selvittää erikseen vaan tyylioppaan määrittämät asiat voidaan toteuttaa suoraviivaisesti. Konkreettinen esimerkki on käytettävät metodit (CRUD), parametrien nimeämiset sekä päivämäärien ja kellonaikojen esittäminen.


API -tyylioppaalla on työtä nopeuttava, APIn rakennetta ja logiikka yhtenäistävä sekä työmukavuutta lisäävä vaikutus.

Mikäli APIen tuottaminen on ulkoistettu osin tai kokonaan toiselle organisaatiolle, on API -tyyliopas väline tehdä APIen määrittelyä linjaavien ratkaisujen osalta yhteen kertaan ja soveltaa uudelleen ja uudelleen. Myös mikäli APIen tuottamiseen osallistuu useampi tiimi (vaikka vain oman talon sisällä), mahdollistaa API -tyyliopas yhtenäisen linjan ja toteutuksen.


Standardit toimintavat mahdollistavat myös valmiskomponenttien valmistuksen ja uudelleenkäytön ilman merkittävää muutosta sekä automaatioprosessien (CI) hyödyntämisen. API -tyylioppaalla on työtä nopeuttava, yhtenäistävä ja työmukavuutta lisäävä vaikutus.


5. APIen testaajan näkökulmasta

API -tyyliopas saattaa ensimmäisellä sivullaan määrittää, että yrityksen REST rajapinnat kuvataan OpenAPI speksin mukaisesti. Koneluettava API -kuvaus luo mahdollisuuksia testauksen toteuttamiseksi.


Joissain yrityksissä vielä kirjoitetaan APIen testit käsin. Syy voi olla, että automaattisesti generoitavat testit eivät tyydytä syystä tai toisesta. Tällöin API -tyylioppaan olemassa olo mahdollistaa testien kirjoittamisen ennen kuin API on toteutettu eli heti design vaiheen jälkeen tai jopa limittäin.


Automaattiset testit eivät testaa "tunnetta", joka APIn käytöstä syntyy.

Kuitenkin yhä useammin testit generoidaan koneluettavasta APIn kuvauksesta. Tällöin testit ovat useimmiten hyvin mekanistisia ja yksinkertaisia ominaisuuksia testaavia testejä. Automaattiset testit eivät testaa "tunnetta", joka APIn käytöstä syntyy. Generoidut testit läpäisevä API voi olla kömpelö käyttää. APIn tuntuman tietää vasta kun sitä kokeilee kirjoittamalla APIa hyödyntävää koodia.


6. APIen hyödyntäjien näkökulmasta

APIen hyödyntäjien näkökulma on yleensä se, jonka kuulen asiakkailta vastauksena kun kysyn asiasta. Eikä mikään ihme, koska tätä on nostettu esiin erityisesti Business to Developer (B2D) ohjelmiin ja kaupallistamiseen liittyvissä kirjoituksissa. Näkökulma on ilmeinen ulkoisille sovelluskehittäjille tarkoitettujen APIen kohdalla, koska he ovat APIn asiakkaita. Ei kuitenkaan kannata jättää sisäisiä hyödyntäjiä tämän näkökulman ulkopuolelle.


API -tyyliopas voi parhaimmillaan johtaa tilanteeseen, että sovelluskehittäjä APIn ensimmäistä kertaa avatessaan tuntee "kuin olisin jo ennenkin käyttänyt" tai asiat vain tuntuu tutulta. Tuttuus, johdonmukaisuus, selkeys ja intuitiivisuus syntyy kun käytetään systemaattisesti hyväksi havaittuja käytäntöjä ja alan standardeja.


Kun APIn kehittäjäkokemus on kohdallaan, APIn kuluttaja pystyy ennakoimaan miten API toimii ja uudet ominaisuudet tuntuvat luontevilta - The Principle of Least Astonishment (5). Parhaimmillaan hyödyntäjä tarvittaessa tarkistaa asian dokumentaatiosta, mutta "osaa" jo muutenkin käytettyjä parametrien nimiä ja osaa odottaa tiettyjä tilakoodeja (status codes).


Toisin sanoen, API on intuitiivinen ja helppo käyttää kunhan se seuraa hyväksi havaittuja toimintatapoja ja standardeja eikä tarjoa yllätyksiä. API saattaa jopa tuntua hieman tylsältä.


Lue lisää aiheesta



Elokuussa ilmestyvässä API -talous101 kirjassa on kirjoittamani API -tyylioppaisiin keskittyvä luku.


Kirja on jo tilattavissa Alma Talent verkkokaupasta. Kirjassa on noin 230 sivua tiukkaa asiaa API-taloudesta ja sen peruskäsitteistä.


Kirjan on kirjoittanut Suomen API -talouden asiantuntijajoukko:


Jarkko Moilanen, Marjukka Niinoja, Marko Seppänen ja Mika Honkanen





Lähteitä

  1. Fielding, Roy T., and Richard N. Taylor. Architectural styles and the design of network-based software architectures. Vol. 7. Doctoral dissertation: University of California, Irvine, 2000.

  2. Murphy, Lauren, et al. "Preliminary Analysis of REST API Style Guidelines." Ann Arbor 1001: 48109.

  3. Moilanen, Jarkko, et al. API -talous 101, Alma Talent, 2018

  4. Macvean, Andrew, Martin Maly, and John Daughtry. "API design reviews at scale." Proceedings of the 2016 CHI Conference Extended Abstracts on Human Factors in Computing Systems. ACM, 2016.

  5. Seebach, Peter. "The cranky user: The Principle of Least Astonishment." IBM DeveloperWorks, 2001.



Tilaa APItalisti tilaisuuteen puhumaan!


Kokenut puhuja jota isotkaan yleisöt tai yllättävät tilanteet eivät jäädytä.

Katso referenssit ja hinnasto sekä tee tilaus.

©2018 by apitalisti
 

Yhteystiedot

Brändit

Apitalist is registered trademark of APInf Ltd

APIOps is registered trademark of Osaango Ltd and APInf Ltd

Tilaa kirja

API -talous 101 -kirja Alma Talent kaupassa!

Podcast

"Opi tuntemaan API -asiakkaasi" podcast -sarja

Lue lisää!