Što je API? Vodič za graditelje aplikacija bez programiranja

API (sučelje za programiranje aplikacija) je definiran način da jedan softver traži od drugoga podatke ili da ga natjera na neku radnju. Vaša aplikacija šalje zahtjev u dogovorenom formatu — „daj mi sutrašnje rezervacije“, „naplati ovu karticu 20 eura“, „sažmi ovaj tekst“ — a drugi sustav vraća strukturiran odgovor. API-ji su način na koji se dijelovi aplikacije međusobno povezuju i kako vaša aplikacija koristi vanjske usluge poput plaćanja, e-maila, karata i AI-ja.

Zašto su API-ji važni kad gradite s AI-jem

Gotovo svaka korisna aplikacija sastoji se od dijelova koji komuniciraju preko API-ja:

• Unutar vaše aplikacije zasloni u pregledniku pozivaju API vaše vlastite pozadine da učitaju i spreme podatke.
• Izvan vaše aplikacije vaša pozadina poziva API-je drugih tvrtki: Stripe za plaćanja, pružatelj e-maila za slanje računa, pružatelj AI modela za generiranje teksta.

Kad od AI graditelja zatražite „prihvaćaj plaćanja“ ili „dodaj AI sažetak“, on zapravo piše kod koji poziva API. Osnove vam pomažu razumjeti što AI treba od vas (obično račun kod te usluge i API ključ), gdje stvari mogu poći po zlu i koliko će koštati.

Svakodnevna usporedba

Zamislite restoran. Ne ulazite u kuhinju i ne kuhate sami. Čitate jelovnik, kažete konobaru što želite na način koji kuhinja razumije, a konobar vam donosi hranu — ili kaže da je jelo rasprodano.

• Jelovnik je API dokumentacija: popis onoga što možete tražiti i kako.
• Konobar je API: jedan dogovoreni način na koji zahtjevi ulaze i odgovori izlaze.
• Kuhinja je drugi sustav: ne morate znati što se događa unutra.
• Vaša narudžba je zahtjev; tanjur je odgovor.

Kuhinja može promijeniti svoje peći i osoblje bez utjecaja na vas, sve dok jelovnik ostaje isti. To je prava vrijednost API-ja: omogućuje dvama sustavima da rade zajedno bez da bilo koji mora znati kako je drugi izgrađen.

Kako radi zahtjev web API-ja

Većina API-ja s kojima ćete se susresti su web API-ji koji rade preko HTTP-ja, istog protokola koji koristi vaš preglednik. Svaki zahtjev ima nekoliko dijelova:

A svaki odgovor ima:

JSON (JavaScript Object Notation) je jednostavan tekstualni format s imenima i vrijednostima u vitičastim zagradama. To je standardan način na koji web API-ji razmjenjuju podatke.

REST: najuobičajeniji stil

REST je široko korištena konvencija za dizajn web API-ja. Svaka vrsta stvari dobiva svoj URL, a standardne metode govore što joj radite. Evo kako bi mogao izgledati REST API za aplikaciju za rezervacije:

PUT također postoji i po konvenciji zamjenjuje cijeli zapis, dok PATCH mijenja samo polja koja pošaljete.

Statusni kodovi koje ćete najčešće vidjeti:

Kad se vaša aplikacija pokvari, statusni kod je često najbrži trag. 401 od pružatelja plaćanja obično znači nedostajući ili pogrešan API ključ; 429 znači da zovete prečesto.

REST nije jedini stil — postoje i GraphQL i API-ji u stilu RPC-a — ali REST je ono što koristi većina usluga i AI-izgrađenih pozadina.

Primjer: potvrda rezervacije

Kad kupac rezervira šišanje u aplikaciji za salon, u sekundi-dvije može se dogoditi nekoliko API poziva:

1. Stranica za rezervaciju u pregledniku šalje POST /api/bookings s uslugom, vremenom i podacima kupca vašoj pozadini.
2. Vaša pozadina provjerava je li termin slobodan, sprema rezervaciju u bazu podataka i vraća 201 Created.
3. Vaša pozadina poziva API pružatelja e-maila s njegovim tajnim ključem: „pošalji ovu potvrdu na lena@example.com“.
4. Ako postoji depozit, vaša pozadina traži od API-ja pružatelja plaćanja da stvori sesiju plaćanja i šalje kupca tamo.
5. Kasnije pružatelj plaćanja poziva vašu aplikaciju da kaže da je plaćanje uspjelo. Taj obrnuti poziv je webhook.

Prva dva koraka su vaš vlastiti API između frontenda i backenda. Koraci 3–5 su API-ji trećih strana.

Uobičajeni pojmovi objašnjeni

Česte pogreške i zablude

• Stavljanje tajnih ključeva u frontend. Sve u kodu koji se izvršava u pregledniku može vidjeti bilo tko tko posjeti stranicu. Tajni ključevi moraju ostati na poslužitelju, u varijablama okruženja ili tajnama.
• Lijepljenje ključeva u chat. Povijest chata može se pohraniti. Umjesto toga koristite značajku tajni vašeg graditelja i opozovite (rotirajte) svaki ključ koji ste izložili.
• Pretpostavka da je API besplatan. Mnogi API-ji naplaćuju po zahtjevu ili po jedinici korištenja — API-ji AI modela naplaćuju po tokenima. Provjerite cijene i postavite ograničenja potrošnje. Pogledajte kako koristiti LLM API-je.
• Neobrađivanje greški. Vanjske usluge padaju, istječu im vremena i dosežu ograničenja. Tražite razumne poruke o greškama i ponovne pokušaje.
• Vjerovanje pregledniku. Vaš vlastiti API mora sam provjeravati dozvole. Skrivanje gumba ne sprječava nekoga da izravno pozove krajnju točku.
• Korištenje živih ključeva tijekom testiranja. Koristite ključeve testnog načina dok ne budete spremni za lansiranje.

Što tražiti od vašeg AI graditelja

• „Koje vanjske API-je ova aplikacija koristi i koliko svaki košta?“
• „Pozivaj API za plaćanja samo s poslužitelja. Čitaj ključ iz varijable okruženja.“
• „Popiši svaku krajnju točku našeg API-ja, što radi i tko je smije pozvati.“
• „Na poslužitelju provjeri da prijavljeni korisnik posjeduje rezervaciju prije ažuriranja ili brisanja.“
• „Ako API za e-mail zakaže, svejedno spremi rezervaciju i zabilježi grešku.“
• „Za sada koristi testni način pružatelja.“

API-ji u Mythexu

Mythex može izgraditi vaš vlastiti API — kao dio web aplikacije ili kao zaseban backend u Nodeu, Pythonu (FastAPI), C# ili Javi koji radi uz vaš frontend — i napisati kod koji poziva vanjske usluge. Ključeve dodajete kao tajne projekta, a ne u chat, i dostupni su vašoj aplikaciji u pregledu i nakon objave. Dokumentacija ima recepte za integraciju bilo kojeg API-ja i izradu REST API backenda.

Pitanja