Millainen on hyvä API? Määritys ei ole helppoa, eikä yhtä reseptiä hyvän APIn luomiseen välttämättä edes ole. On kuitenkin olemassa käytäntöjä, joiden avulla voi saada aikaan parhaiten käyttötarkoitukseen sopivan API:n. Tähän blogiin on kerätty muutamia havaintoja, jotka olemme Digialla havainneet hyväksi API-kehityksessä.
Huonoa API:a ei kukaan todellisuudessa halua käyttää ja sen kehittämiseen käytetyt resurssit ovat tällöin menneet hukkaan. Syitä huonoon API:in voi olla monia: API voi olla liian hankala käytettäväksi, se ei tue useimpien käyttäjien käyttämää dataformaattia, sen dokumentaatio on olematon tai käyttö voi olla jopa turvallisuusriski.
Monilla on mielipiteitä siitä, onko hyvä API esimerkiksi SOAP, REST, JSON API tai jokin muu. Myös näiden tyylien sisällä on suuria eroja siinä, mikä on hyvä ja mikä ei. Esimerkiksi monen mielestä REST API ei ole REST ellei siinä käytetä hypermediaa, eli REST API:n vastauksen pitäisi sisältää hyperlinkkejä muihin käytettävissä oleviin resursseihin. Tällä hetkellä JSON -pohjaiset API:t kuten REST API:t ovat voimakkaassa nosteessa ja yhä vähemmän tehdään XML -pohjaisia, kuten SOAP:a.
REST on tällä hetkellä kenties suosituin, kun puhutaan Web API:sta. Mutta mitä asioita pitäisi REST:n kohdalla ottaa huomioon? Minkä tahansa REST API:n tulisi noudattaa ainakin näitä kahta periaatetta: käytetään resursseja, ei siis funktioita ja käytetään tarkoituksenmukaista http-verbiä. REST:ssä siis yleensä käytetään http-protokollaa ja sen tarjoamia metodeja, sekä http-vastauskoodeja. Formaattina käytetään yleisesti JSON:ia, sillä se on helposti ymmärrettävää ja huomattavasti keveämpi kuin XML.
Suunnitteluvaiheessa on hyvä käyttää Open API -spesifikaatiota, jolloin voidaan luoda YAML tai JSON -muotoinen kuvaus koko API:sta. Tähän löytyy myös useita työkaluja, joiden avulla voidaan esimerkiksi visualisoida API:a tai generoida koodia luodusta speksistä. Jos on REST APIn dataa mallinnettaessa mahdollista käyttää olemassa olevia datamalleja (mm. schema.org:sta), niin silloin JSON-LD standardia kannattaa käyttää. Turvallisuusasioissa kannattaa muistaa OAuth2 ja OpenID, mikäli käyttäjien autentikointi on tarpeen.
Hyvässä API:ssa ei kuitenkaan ole kyse pelkästään siitä, onko API teknisesti hyvin toteutettu tai siitä, onko käytettyä arkkitehtuuria seurattu oikeaoppisesti. Yksi väite, joka pätee mihin tahansa Web API:in on, että hyvä API on sellainen, jota käyttäjät haluavat käyttää, koska API on hyödyllinen ja helppokäyttöinen.
Kun yrityksesi alkaa miettiä, millaista API:a rakentaa, kannattaa aloittaa siitä, mitä API:lla voidaan tarjota. On myös syytä määrittää tarkkaan keitä sen käyttäjät ovat, mitä käyttäjät API:lla tekevät, mitä hyötyä se tuo käyttäjille ja yritykselle, sekä mitä mahdollisia riskejä tai ongelmia API voi tuoda esille.
Liian monipuolinen API on myös monimutkainen.
APIen suhteen on hyvä muistaa single responsibility principle, eli tee yksi asia, mutta tee se hyvin. Liian monipuolinen API on myös monimutkainen, jolloin API:n käyttäminen vaikeutuu ja mahdollisesti myös vasteajat kasvavat. Tällainen API myös todennäköisesti sisältää suuren määrän koodia ja tekee sen ylläpitämisestä, sekä päivittämisestä hankalaa.
Hyvä dokumentaatio on tärkeä osa hyvää API:a. Tähän on monia keinoja, mutta esimerkiksi REST APIen kanssa on hyvä käyttää yhä yleisemmin käytettävää Open API -spesifikaatiota. Erityisesti kehittäjille hyvästä dokumentaatiosta on hyötyä, sillä se helpottaa API:n testaamista ja käyttöönottoa.
Kannattaa myös miettiä sitä, miten kehittäjät pääsevät käyttämään API:a. Hyväkin API voi jäädä vähälle käytölle, jos sitä ei löydetä tai päästä käyttämään. On olemassa monia tapoja hallita API:en käyttöä. Esimerkiksi IBM:ltä ja Microsoftilta löytyy tähän tarkoitukseen tehdyt palvelut, mutta myös open-source vaihtoehtoja löytyy.
Lyhyesti voidaan tiivistää muutama hyvä käytäntö ”hyvälle” API:lle: hyvä API on käyttäjille arvokas, helppokäyttöinen, hyvin dokumentoitu ja tekee yhden asian, mutta tekee sen hyvin!
Lue myös Jaakko Rajaniemien blogikirjoitus "API-strategia: miksi ja miten?"