Mikä on API? Selkeä opas sovellusrakentajille

API (application programming interface) on määritelty tapa, jolla yksi ohjelmisto pyytää toiselta dataa tai saa sen tekemään jotain. Sovelluksesi lähettää pyynnön sovitussa muodossa — ”anna huomisen varaukset”, ”veloita tämä kortti 20 eurolla”, ”tiivistä tämä teksti” — ja toinen järjestelmä palauttaa jäsennellyn vastauksen. API:t ovat tapa, jolla sovelluksen osat puhuvat keskenään, ja tapa, jolla sovelluksesi käyttää ulkopuolisia palveluita, kuten maksuja, sähköpostia, karttoja ja tekoälyä.

Miksi API:t ovat tärkeitä tekoälyllä rakennettaessa

Lähes jokainen hyödyllinen sovellus koostuu osista, jotka kommunikoivat API:jen kautta:

• Sovelluksesi sisällä selaimen näkymät kutsuvat omaa backendiäsi API:lla ladatakseen ja tallentaakseen dataa.
• Sovelluksesi ulkopuolella backendisi kutsuu muiden yritysten API:ja: Stripe ottaa maksut, sähköpostipalvelu lähettää kuitit, tekoälymallin palveluntarjoaja tuottaa tekstin.

Kun pyydät tekoälyrakentajaa ”ottamaan maksut” tai ”lisäämään tekoälyyhteenvedon”, se kirjoittaa koodia, joka kutsuu API:a. Perusteiden tunteminen auttaa ymmärtämään, mitä tekoäly tarvitsee sinulta (yleensä tilin kyseisessä palvelussa ja API-avaimen), missä asiat voivat mennä pieleen ja mitä ne maksavat.

Arkinen vertauskuva

Ajattele ravintolaa. Et mene keittiöön keittämään. Luet ruokalistan, kerrot tarjoilijalle, mitä haluat keittiön ymmärtämällä tavalla, ja tarjoilija tuo ruoan takaisin — tai kertoo, että annos on loppu.

• Ruokalista on API-dokumentaatio: lista siitä, mitä voit pyytää ja miten.
• Tarjoilija on API: yksi sovittu tapa, jolla pyynnöt tulevat sisään ja vastaukset ulos.
• Keittiö on toinen järjestelmä: sen sisäistä toimintaa ei tarvitse tuntea.
• Tilauksesi on pyyntö; annos on vastaus.

Keittiö voi vaihtaa uuneja ja henkilökuntaa sinuun vaikuttamatta, kunhan ruokalista pysyy samana. Siinä on API:n todellinen arvo: se antaa kahden järjestelmän toimia yhdessä ilman, että kumpikaan tarvitsee tietää, miten toinen on rakennettu.

Miten web-API-pyyntö toimii

Useimmat API:t, joita kohtaat, ovat web-API:ja, jotka toimivat HTTP:n yli — samalla protokollalla, jota selaimesi käyttää. Jokaisessa pyynnössä on muutama osa:

Ja jokaisessa vastauksessa on:

JSON (JavaScript Object Notation) on yksinkertainen tekstimuoto, jossa on nimiä ja arvoja aaltosulkeissa. Se on web-API:en vakiotapa vaihtaa dataa.

REST: yleisin tyyli

REST on laajasti käytetty käytäntö web-API:en suunnitteluun. Jokaisella asiatyypillä on oma URL-osoitteensa, ja vakiometodit kertovat, mitä sille tehdään. Tältä REST-API varaussovellukselle voi näyttää:

PUT on myös olemassa ja yleisesti korvaa koko tietueen, kun taas PATCH muuttaa vain lähettämiäsi kenttiä.

Yleisimmät tilakoodit:

Kun sovelluksesi hajoaa, tilakoodi on usein nopein vihje. 401 maksupalvelusta tarkoittaa yleensä puuttuvaa tai väärää API-avainta; 429 tarkoittaa, että kutsut liian usein.

REST ei ole ainoa tyyli — myös GraphQL- ja RPC-tyyliset API:t ovat olemassa — mutta REST on sitä, mitä useimmat palvelut ja tekoälyllä rakennetut backendit käyttävät.

Esimerkki: varausvahvistus

Kun asiakas varaa hiustenleikkuun kampaamosovelluksessa, useita API-kutsuja voi tapahtua sekunnin tai parin aikana:

1. Selaimen varaussivu lähettää POST /api/bookings -pyynnön palvelu-, aika- ja asiakastietojen kanssa backendiisi.
2. Backendisi tarkistaa, että aika on vapaa, tallentaa varauksen tietokantaan ja palauttaa 201 Created.
3. Backendisi kutsuu sähköpostipalvelun API:a salaisella avaimellaan: ”lähetä tämä vahvistus osoitteeseen lena@example.com.”
4. Jos on ennakkomaksu, backendisi pyytää maksupalvelun API:lta kassaistuntoa ja lähettää asiakkaan sinne.
5. Myöhemmin maksupalvelu kutsuu sinun sovellustasi kertoakseen, että maksu onnistui. Tuo käänteinen kutsu on webhook.

Kaksi ensimmäistä askelta ovat omaa API:asi frontendin ja backendin välillä. Askeleet 3–5 ovat kolmannen osapuolen API:ja.

Keskeiset termit selitettynä

Yleisiä virheitä ja väärinkäsityksiä

• Salaisten avainten laittaminen frontendiin. Kaikki koodi, joka ajetaan selaimessa, voi nähdä kuka tahansa, joka vierailee sivulla. Salaiset avaimet pitää pitää palvelimella, ympäristömuuttujissa tai salaisuuksissa.
• Avainten liittäminen chattiin. Chatin historia voidaan tallentaa. Käytä sen sijaan rakentajasi salaisuusominaisuutta ja vaihda kaikki avaimet, jotka olet paljastanut.
• Oletus, että API on ilmainen. Monet API:t veloittavat pyyntöä tai käyttöyksikköä kohden — tekoälymallien API:t veloittavat tokeneista. Tarkista hinnoittelu ja aseta kulutusrajat. Katso kuinka LLM-API:ja käytetään.
• Virheiden käsittelemättä jättäminen. Ulkopuoliset palvelut menevät alas, aikakatkaistuvat ja osuvat rajoihin. Pyydä järkeviä virheviestejä ja uusintayrityksiä.
• Selaimeen luottaminen. Oman API:si pitää itse tarkistaa oikeudet. Painikkeen piilottaminen ei estä ketään kutsumasta päätepistettä suoraan.
• Live-avainten käyttö testatessa. Käytä testitilan avaimia, kunnes olet valmis lanseeraamaan.

Mitä pyytää tekoälyrakentajalta

• ”Mitä ulkopuolisia API:ja tämä sovellus käyttää, ja mitä kukin maksaa?”
• ”Kutsu maksupalvelun API:a vain palvelimelta. Lue avain ympäristömuuttujasta.”
• ”Listaa jokainen päätepiste API:ssamme, mitä se tekee ja kuka saa kutsua sitä.”
• ”Tarkista palvelimella, että kirjautunut käyttäjä omistaa varauksen ennen sen päivittämistä tai poistamista.”
• ”Jos sähköposti-API epäonnistuu, tallenna varaus silti ja kirjaa virhe.”
• ”Käytä toistaiseksi palveluntarjoajan testitilaa.”

API:t Mythexissä

Mythex voi rakentaa oman API:si — osana web-sovellusta tai erillisenä backendinä Nodessa, Pythonissa (FastAPI), C#:ssa tai Javassa frontendisi rinnalla — ja kirjoittaa koodin, joka kutsuu ulkopuolisia palveluita. Lisäät niiden avaimet projektin salaisuuksina eikä chatissa, ja ne ovat sovelluksesi käytettävissä esikatselussa ja julkaisun jälkeen. Dokumentaatiossa on reseptit minkä tahansa API:n integrointiin ja REST API -backendin rakentamiseen.

Kysymykset