Kaj je API? Vodnik za graditelje aplikacij brez strokovnega ozadja

API (vmesnik za programiranje aplikacij) je določen način, kako ena programska oprema zahteva podatke od druge ali ji naroči, naj nekaj naredi. Vaša aplikacija pošlje zahtevo v dogovorjeni obliki — »daj mi jutrišnje rezervacije«, »zaračunaj tej kartici 20 evrov«, »povzemi to besedilo« — drugi sistem pa pošlje nazaj strukturiran odgovor. API-ji so način, kako se deli aplikacije pogovarjajo med seboj in kako vaša aplikacija uporablja zunanje storitve, kot so plačila, e-pošta, zemljevidi in AI.

Zakaj so API-ji pomembni pri gradnji z AI

Skoraj vsaka koristna aplikacija je sestavljena iz delov, ki komunicirajo prek API-jev:

• Znotraj vaše aplikacije zasloni v brskalniku kličejo API vašega lastnega zaledja, da naložijo in shranijo podatke.
• Zunaj vaše aplikacije vaše zaledje kliče API-je drugih podjetij: Stripe za sprejem plačil, ponudnika e-pošte za pošiljanje računov, ponudnika AI modelov za ustvarjanje besedila.

Ko AI graditelju rečete »sprejmi plačila« ali »dodaj povzetek AI«, dejansko napiše kodo, ki kliče API. Če poznate osnove, razumete, kaj AI potrebuje od vas (običajno račun pri tej storitvi in API-ključ), kje lahko stvari gredo narobe in koliko bodo stale.

Vsakdanja primerjava

Pomislite na restavracijo. Ne greste v kuhinjo in ne kuhate sami. Preberete jedilnik, natakarju poveste, kaj želite, na način, ki ga kuhinja razume, natakar pa vam prinese hrano — ali pa vam pove, da je jed pošla.

• Jedilnik je dokumentacija API-ja: seznam, kaj lahko zahtevate in kako.
• Natakar je API: en dogovorjen način, kako zahteve vstopajo in odgovori izstopajo.
• Kuhinja je drugi sistem: ne rabite vedeti, kako deluje znotraj.
• Vaše naročilo je zahteva; krožnik je odgovor.

Kuhinja lahko zamenja pečice in osebje, ne da bi to vplivalo na vas, dokler jedilnik ostane enak. To je prava vrednost API-ja: omogoča, da dva sistema delata skupaj, pri čemer nobeden ne potrebuje vedeti, kako je drugi zgrajen.

Kako deluje zahteva spletnega API-ja

Večina API-jev, s katerimi se boste srečali, so spletni API-ji, ki delujejo prek HTTP, istega protokola, ki ga uporablja vaš brskalnik. Vsaka zahteva ima nekaj delov:

In vsak odgovor ima:

JSON (JavaScript Object Notation) je preprost besedilni format imen in vrednosti v zavitih oklepajih. Je standarden način, kako spletni API-ji izmenjujejo podatke.

REST: najpogostejši slog

REST je široko uporabljena konvencija za oblikovanje spletnih API-jev. Vsaka vrsta stvari dobi svoj naslov URL, standardne metode pa povejo, kaj počnete z njo. Tako bi lahko izgledal REST API za aplikacijo za rezervacije:

PUT tudi obstaja in po dogovoru zamenja celoten zapis, medtem ko PATCH spremeni samo polja, ki jih pošljete.

Najpogostejše statusne kode:

Ko se vaša aplikacija pokvari, je statusna koda pogosto najhitrejši namig. 401 od ponudnika plačil običajno pomeni manjkajoč ali napačen API-ključ; 429 pomeni, da kličete prepogosto.

REST ni edini slog — obstajajo tudi GraphQL in API-ji v slogu RPC — vendar je REST tisto, kar uporablja večina storitev in zaledij, zgrajenih z AI.

Delovni primer: potrditev rezervacije

Ko stranka rezervira striženje v aplikaciji za salon, se lahko v eni ali dveh sekundah zgodi več klicev API-ja:

1. Stran za rezervacije v brskalniku pošlje POST /api/bookings s storitvijo, časom in podatki o stranki na vaše zaledje.
2. Vaše zaledje preveri, ali je termin prost, shrani rezervacijo v bazo podatkov in vrne 201 Created.
3. Vaše zaledje pokliče API ponudnika e-pošte s svojim skrivnim ključem: »pošlji to potrditev na lena@example.com«.
4. Če je potreben polog, vaše zaledje prosi API ponudnika plačil, naj ustvari plačilno sejo, in stranko pošlje tja.
5. Pozneje ponudnik plačil pokliče vašo aplikacijo, da sporoči, da je plačilo uspelo. Ta obratni klic je webhook.

Prva dva koraka sta vaš lastni API med sprednjim in zadnjim delom. Koraki 3–5 so API-ji tretjih oseb.

Pogosti pojmi pojasnjeni

Pogoste napake in zmote

• Shranjevanje skrivnih ključev v sprednjem delu. Vse, kar je v kodi, ki teče v brskalniku, lahko vidi kdorkoli, ki obišče stran. Skrivni ključi morajo ostati na strežniku, v okoljskih spremenljivkah ali skrivnostih.
• Lepljenje ključev v klepet. Zgodovina klepeta je lahko shranjena. Raje uporabite funkcijo skrivnosti v svojem graditelju in zamenjajte vsak ključ, ki ste ga izpostavili.
• Predpostavka, da je API brezplačen. Številni API-ji zaračunavajo na zahtevo ali na enoto porabe — API-ji AI modelov zaračunavajo po žetonih. Preverite cene in nastavite omejitve porabe. Glejte kako uporabljati API-je LLM.
• Nepripravljenost na napake. Zunanje storitve odpovedo, zamudijo in dosežejo omejitve. Zahtevajte smiselna sporočila o napakah in ponovne poskuse.
• Zaupanje brskalniku. Vaš lastni API mora sam preveriti dovoljenja. Skrivanje gumba ne ustavi nekoga, ki kliče končno točko neposredno.
• Uporaba živih ključev med preizkušanjem. Med testiranjem uporabite ključe testnega načina, dokler niste pripravljeni na izdajo.

Kaj zahtevati od svojega AI graditelja

• „Katere zunanje API-je ta aplikacija uporablja in koliko stane vsak?“
• „Kliči API za plačila samo s strežnika. Ključ preberi iz okoljske spremenljivke.“
• „Našteji vsako končno točko v našem API-ju, kaj počne in kdo jo sme klicati.“
• „Na strežniku preveri, da prijavljeni uporabnik lastni rezervacijo, preden jo posodobiš ali izbrišeš.“
• „Če API za e-pošto odpove, shrani rezervacijo vseeno in zabeleži napako.“
• „Za zdaj uporabljaj testni način ponudnika.“

API-ji v Mythexu

Mythex lahko zgradi vaš lastni API — kot del spletne aplikacije ali kot ločeno zaledje v Node, Pythonu (FastAPI), C# ali Javi, ki teče poleg vašega sprednjega dela — in napiše kodo, ki kliče zunanje storitve. Ključe dodate kot skrivnosti projekta, ne v klepet, na voljo pa so vaši aplikaciji v predogledu in po objavi. Dokumentacija ima recepte za vključevanje poljubnega API-ja in gradnjo zaledja REST API.

Vprašanja