Mis on API? Lihtne juhend rakenduste ehitajatele

API (application programming interface) on kokkulepitud viis, kuidas üks tarkvara küsib teiselt andmeid või palub tal midagi teha. Su rakendus saadab päringu kokkulepitud vormingus — „anna mulle homsed broneeringud“, „võta sellelt kaardilt 20 €“, „võta see tekst kokku“ — ja teine süsteem saadab struktureeritud vastuse. API-d on see, kuidas rakenduse osad omavahel räägivad, ja kuidas su rakendus kasutab väliseid teenuseid nagu maksed, e-post, kaardid ja AI.

Miks API-d tehisintellektiga ehitades oluline on

Peaaegu iga kasulik rakendus koosneb osadest, mis suhtlevad API-de kaudu:

• Rakenduse sees kutsuvad brauseris olevad ekraanid sinu enda backendi API-d andmete laadimiseks ja salvestamiseks.
• Rakenduse väljas kutsub su backend teiste ettevõtete API-sid: Stripe võtab makseid vastu, e-posti pakkuja saadab kviitungeid, AI mudeli pakkuja genereerib teksti.

Kui palud AI-ehitajalt „võta makseid“ või „lisa AI kokkuvõte“, kirjutab ta tegelikult koodi, mis kutsub API-d. Põhitõdede tundmine aitab mõista, mida AI sinult vajab (tavaliselt konto selle teenusega ja API-võti), kus asjad võivad valesti minna ja mis need maksma lähevad.

Igapäevane näide

Mõtle restoranile. Sa ei lähe kööki ja ei tee ise süüa. Loed menüüd, ütled ettekandjale, mida tahad, viisil, mida köök mõistab, ja ettekandja toob su toidu tagasi — või ütleb, et roog on otsas.

• Menüü on API dokumentatsioon: loend sellest, mida võid tellida ja kuidas.
• Ettekandja on API: üks kokkulepitud viis, kuidas päringud sisse ja vastused välja tulevad.
• Köök on teine süsteem: sa ei pea teadma, kuidas see sees töötab.
• Sinu tellimus on päring; taldrik on vastus.

Köök võib oma ahjusid ja personali muuta, ilma et see sind mõjutaks, kui menüü jääb samaks. Selles seisneb API tegelik väärtus: see laseb kahel süsteemil koos töötada, ilma et kumbki peaks teadma, kuidas teine on ehitatud.

Kuidas veebi-API päring töötab

Enamik API-sid, millega kokku puutud, on veebi-API-d, mis töötavad HTTP kaudu — sama protokolliga, mida su brauser kasutab. Igal päringul on mõned osad:

Ja igal vastusel on:

JSON (JavaScript Object Notation) on lihtne tekstivorming nimedest ja väärtustest looksulgudes. See on veebi-API-de standardne viis andmete vahetamiseks.

REST: kõige levinum stiil

REST on laialdaselt kasutatav kokkulepe veebi-API-de disainimiseks. Igal asjatüübil on oma URL ning standardsed meetodid ütlevad, mida sa sellega teed. Siin on, kuidas broneerimisrakenduse REST-API võiks välja näha:

PUT on samuti olemas ja tavaliselt asendab terve kirje, samas kui PATCH muudab ainult saadetud välju.

Kõige sagedamini nähtavad staatusekoodid:

Kui su rakendus katkeb, on staatusekood sageli kiireim vihje. 401 maksepakkujalt tähendab tavaliselt puuduvat või valet API-võtit; 429 tähendab, et helistad liiga tihti.

REST ei ole ainus stiil — olemas on ka GraphQL ja RPC-stiilis API-d — aga REST on see, mida enamik teenuseid ja AI-ehitatud backend'e kasutab.

Töötav näide: broneeringu kinnitus

Kui klient broneerib soengu ilu-salongi rakenduses, võib mõne sekundi või kahe jooksul toimuda mitu API-kutset:

1. Brauseris olev broneerimisleht saadab POST /api/bookings teenuse, aja ja kliendi andmetega sinu backendile.
2. Su backend kontrollib, et ajavahemik on vaba, salvestab broneeringu andmebaasi ja tagastab 201 Created.
3. Su backend kutsub e-posti pakkuja API-d oma salajase võtmega: „saada see kinnitus aadressile lena@example.com.“
4. Kui on ettemaks, palub su backend maksepakkuja API-lt kassa sessiooni loomist ja saadab kliendi sinna.
5. Hiljem helistab maksepakkuja sinu rakendusele, et öelda, et makse õnnestus. See vastupidine kõne on webhook.

Esimesed kaks sammu on sinu enda API frontendi ja backend'i vahel. Sammud 3–5 on kolmanda osapoole API-d.

Levinud mõisted selgitatuna

Levinud vead ja väärarusaamad

• Salajaste võtmete panemine frontend'i. Kõik, mis on koodis, mida brauser käivitab, on kõigile nähtav, kes saidi külastab. Salajased võtmed peavad jääma serverisse, keskkonnamuutujates või saladustes.
• Võtmete kleepimine vestlusse. Vestluse ajalugu võib olla salvestatud. Kasuta selle asemel oma ehitaja saladuste funktsiooni ja vaheta välja iga võti, mille oled avalikuks teinud.
• Eeldamine, et API on tasuta. Paljud API-d võtavad tasu päringu või kasutusühiku pealt — AI mudeli API-d küsivad tasu tokenite järgi. Kontrolli hindu ja sea kulupiirangud. Vaata kuidas kasutada LLM-API-sid.
• Vea käsitlemata jätmine. Välised teenused lähevad maha, aeguvad ja jõuavad piirangutesse. Palu mõistlikke veateateid ja kordusi.
• Brauseri usaldamine. Su enda API peab ise kontrollima õigusi. Nupu peitmine ei takista kedagi lõpp-punkti otse kutsumast.
• Live-võtmete kasutamine testimisel. Kasuta testrežiimi võtmeid, kuni oled valmis lansseerima.

Mida paluda oma AI-ehitajalt

• „Milliseid väliseid API-sid see rakendus kasutab ja mis iga maksab?“
• „Kutsu maksete API-d ainult serverist. Loe võti keskkonnamuutujast.“
• „Loetle iga lõpp-punkt meie API-s, mida see teeb ja kes tohib seda kutsuda.“
• „Kontrolli serveris, et sisseloginud kasutaja omab broneeringut enne selle muutmist või kustutamist.“
• „Kui e-posti API ebaõnnestub, salvesta broneering ikka ja logi viga.“
• „Kasuta praegu pakkuja testrežiimi.“

API-d Mythexis

Mythex saab ehitada su enda API-d — osana veebirakendusest või eraldi backend'ina Node'is, Pythonis (FastAPI), C#-is või Javas, mis töötab koos sinu frontend'iga — ning kirjutada koodi, mis kutsub väliseid teenuseid. Lisad nende võtmed projekti saladustena, mitte vestluses, ja need on rakendusele kättesaadavad eelvaates ning pärast avaldamist. Dokumentatsioonis on retseptid mis tahes API integreerimiseks ja REST-API backend'i ehitamiseks.

Küsimused