Mikä on API? REST API selkeästi

01Mikä on API? Tarjoilijavertaus

Tunnetuin tapa selittää, mikä API on, on ravintolavertaus. Sinä olet asiakas, ja keittiö on järjestelmä, joka pitää dataa. Keittiöön et pääse itse; katsot ruokalistaa ja annat tilauksen tarjoilijalle. Tarjoilija välittää pyynnön keittiöön ja tuo valmiin ruoan sinulle. Tässä tilanteessa tarjoilija on API.

Myös ruokalista on API:n dokumentaatio: se kertoo, mitä voit pyytää, miten pyydät ja mitä saat vastineeksi. Mitä ei ole ruokalistalla, sitä et voi pyytää; sinun ei myöskään tarvitse tietää, miten keittiö toimii.

Ohjelmistomaailmassa tämä järjestely tuo suuren helpotuksen. Verkkokaupan ei tarvitse tuntea kuljetusyrityksen sisäistä järjestelmää; se sanoo kuljetusyrityksen tarjoamalle API:lle ”luo tarra tälle lähetykselle” ja saa vastauksen. Kumpikin osapuoli voi muuttaa omaa sisäistä rakennettaan, kunhan API-sopimus säilyy.

02Mihin API:a tarvitaan?

Vastaus kysymykseen, mihin API:a tarvitaan, piilee lähes jokaisessa päivittäin käyttämässäsi digitaalisessa palvelussa. Sijainnin valinta kartalta sivustolla, korttimaksu, kirjautuminen Googlella tai sääennusteen katsominen on taustalla API-kutsu.

• Yhdistää järjestelmät toisiinsa: sivusto, markkinapaikka, kuljetus, kirjanpito ja maksujärjestelmät toimivat samassa virrassa.
• Vähentää käsin tehtävää syöttöä: tilaus-, varasto- ja laskutiedot siirtyvät järjestelmästä toiseen itsestään.
• Syöttää mobiilisovelluksia: puhelimen sovellus saa datan API:lta, ei suoraan tietokannasta.
• Mahdollistaa valmiiden palvelujen käytön: maksu-, kartta-, tekstiviesti- tai sähköpostiinfrastruktuuria ei tarvitse kirjoittaa alusta alkaen.
• Tarjoaa turvallisen pääsyn: ulkopuoliselle avataan vain sallitut toimenpiteet, ei koko tietokantaa.

03Mikä on REST API?

API:t voidaan suunnitella eri tyyleillä; verkossa yleisin on REST-lähestymistapa. Lyhyt vastaus kysymykseen mikä on REST API: HTTP-protokollaa käyttävä API-tyyli, joka määrittelee jokaisen tiedon osoitteella (resurssi) ja tekee näille resursseille toimenpiteitä vakiometodeilla.

RESTissä kaikki on resurssi: tuotteet, tilaukset, asiakkaat. Jokaisella resurssilla on osoite, ja se, millä HTTP-metodilla siihen mennään, määrää, mitä haluat tehdä. Vastaukset palautuvat useimmiten JSON-muodossa; se on tekstiformaatti, jonka sekä ihminen voi lukea että ohjelmat käsitellä helposti.

Mikä on päätepiste (endpoint)?

Päätepiste (endpoint) on API:ssa osoite, jossa tietty toimenpide tehdään. Esimerkiksi /api/urunler on tuotelistan ja /api/urunler/42 tuotteen numero 42 päätepiste. API-dokumentaatio on pohjimmiltaan luettelo näistä päätepisteistä, siitä millä metodilla niitä kutsutaan ja mitä ne palauttavat.

Tilakoodit

Jokaisen vastauksen mukana tulee HTTP-tilakoodi, joka tiivistää toimenpiteen tuloksen. 200 tarkoittaa onnistunutta, 201 tietue luotu, 400 virheellinen pyyntö, 401 tunnistautumaton, 403 ei oikeutta, 404 ei löytynyt, 429 liian monta pyyntöä ja 500 palvelinvirhe. Hyvä integraatio käsittelee jokaisen koodin erikseen.

04Miltä API-pyyntö näyttää?

API-pyyntö koostuu pohjimmiltaan neljästä osasta: osoitteesta, metodista, otsikoista (tunnistetiedot, datatyyppi) ja tarvittaessa rungosta (lähetettävä data). Alla näkyy yksinkertainen lukupyyntö julkiseen testi-API:in ja tyypillinen JSON-vastaus.

Tämän pyynnön voi lähettää päätteestä curlilla, selaimesta JavaScriptillä tai palvelimella Pythonilla tai Node.js:llä; säännöt ovat samat, vain käytetty työkalu vaihtuu.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05API-tietoturva ja tunnistautuminen

Julkisia testi-API:ita lukuun ottamatta et pääse todelliseen API:in todistamatta, kuka olet. Yleisimmät menetelmät ovat API-avain, lyhytikäiset käyttöoikeustunnisteet (token) ja OAuthin kaltaiset valtuutuskulut.

Tietoturva ei rajoitu pelkkään tunnistautumiseen. Hyvin suunniteltu API antaa jokaiselle käyttäjälle vain tarvittavat oikeudet, validoi saapuvan datan ja rajoittaa pyyntöjen määrää väärinkäytön estämiseksi (rate limit).

• Älä koskaan laita API-avaimia selaimelle meneviin koodeihin tai julkiseen tietovarastoon.
• Muodosta yhteys aina HTTPS:n kautta.
• Säilytä avaimet ympäristömuuttujissa ja uusi ne säännöllisin väliajoin.
• Pyydä vain tarvittavat oikeudet; jos lukuoikeus riittää, älä ota kirjoitusoikeutta.
• Älä vuoda sisäisten järjestelmien yksityiskohtia virhevastauksissa.

06Esimerkkejä API-integraatiosta

API-integraatio tarkoittaa kahden tai useamman järjestelmän yhdistämistä niin, että ne vaihtavat tietoa säännöllisesti ja automaattisesti API:en kautta. Verkkokauppayrityksen päivittäisessä työnkulussa nähdään lähes kaikki nämä yhteydet.

Kun tilaus tulee, varasto päivittyy kaikissa kanavissa, joissa tuotetta myydään; tämä hoituu markkinapaikkaintegraatiolla. Kun tilaus vahvistetaan, kuljetusyritykseltä haetaan tarra ja seurantanumero; tämä vaihe kuuluu kuljetusintegraatioon. Lasku taas luodaan ja lähetetään asiakkaalle itsestään Verkkolasku-integraatiolla (Turkin sähköinen laskutusjärjestelmä).

Kaikissa näissä yhteyksissä vaikeaa ei ole ensimmäisen kutsun tekeminen. Vastaukset kysymyksiin, mitä tapahtuu, kun vastapuoli ei vastaa, miten estetään saman tilauksen käsittely kahdesti ja ketä informoidaan virheen sattuessa, ratkaisevat eron vankan integraation ja hauraan yhteyden välillä.

API vai webhook?

API:ssa sinä kysyt ja vastapuoli vastaa. Webhookissa taas vastapuoli ilmoittaa sinulle itsestään, kun jokin tapahtuma tapahtuu. Sen sijaan, että kysyisit jatkuvasti ”onko uusia tilauksia”, ilmoituksen saaminen tilauksen tullessa on usein tehokkaampaa; yksityiskohdat kirjoituksessa mikä on webhook.

07Mistä API-kehitys kannattaa aloittaa?

API:n käytön oppimiseen hyvä alku on valita julkinen testi-API ja lähettää pyyntöjä curlilla tai API-testityökalulla. Vastausten lukeminen, tilakoodien tulkinta ja virhetilanteiden kokeilu juurruttavat käsitteet nopeasti.

Jos haluat kirjoittaa oman API:si, sinun on valittava taustajärjestelmän kieli. Nopeaa ja luettavaa alkua varten voit katsoa FastAPI-esimerkkiä kirjoituksessa mikä on Python tai, jos haluat edetä JavaScriptillä, Express-esimerkkiä kirjoituksessa mikä on Node.js.

Hyvällä API:lla on joka tapauksessa kolme yhteistä piirrettä: selkeä ja ajantasainen dokumentaatio, johdonmukainen nimeäminen ja ennustettavat virhevastaukset. Jos API:a käyttävä kehittäjä pystyy lukemaan dokumentaation ja tekemään ensimmäisen pyyntönsä muutamassa minuutissa, suunnittelu on oikealla tiellä.