Ce este un API? Ghid simplu pentru constructorii de aplicații

Un API (application programming interface) este un mod definit prin care o bucată de software cere date unei alte bucăți sau îi cere să facă ceva. Aplicația ta trimite o cerere într-un format convenit — „dă-mi rezervările de mâine”, „taxează acest card cu 20 de euro”, „rezumă acest text” — iar celălalt sistem trimite înapoi un răspuns structurat. API-urile sunt modul în care părțile unei aplicații comunică între ele și modul în care aplicația ta folosește servicii externe, cum ar fi plățile, emailul, hărțile și AI-ul.

De ce contează API-urile când construiești cu AI

Aproape orice aplicație utilă este făcută din părți care comunică prin API-uri:

• În interiorul aplicației, ecranele din browser apelează API-ul backend-ului tău ca să încarce și să salveze date.
• În afara aplicației, backend-ul tău apelează API-urile altor companii: Stripe ca să preia plăți, un furnizor de email ca să trimită chitanțe, un furnizor de modele AI ca să genereze text.

Când ceri unui constructor AI să „preia plăți” sau să „adauge un rezumat AI”, ce face de fapt este să scrie cod care apelează un API. Dacă știi elementele de bază, înțelegi ce are nevoie AI-ul de la tine (de obicei un cont la acel serviciu și o cheie API), unde pot merge lucrurile prost și cât vor costa.

O analogie din viața de zi cu zi

Gândește-te la un restaurant. Nu intri în bucătărie ca să gătești. Citești meniul, îi spui chelnerului ce vrei într-un mod pe care bucătăria îl înțelege, iar chelnerul îți aduce mâncarea — sau îți spune că preparatul s-a terminat.

• Meniul este documentația API: lista a ceea ce poți cere și a modului în care.
• Chelnerul este API-ul: singurul mod convenit prin care cererile intră și răspunsurile ies.
• Bucătăria este celălalt sistem: nu trebuie să știi cum funcționează pe dinăuntru.
• Comanda ta este cererea; farfuria este răspunsul.

Bucătăria își poate schimba cuptoarele și personalul fără să te afecteze, atâta timp cât meniul rămâne același. Asta este valoarea reală a unui API: lasă două sisteme să lucreze împreună fără ca vreunul să trebuiască să știe cum este construit celălalt.

Cum funcționează o cerere API web

Majoritatea API-urilor cu care te vei întâlni sunt API-uri web, care funcționează prin HTTP, același protocol pe care îl folosește browserul. Fiecare cerere are câteva părți:

Și fiecare răspuns are:

JSON (JavaScript Object Notation) este un format text simplu, cu nume și valori între acolade. Este modul standard prin care API-urile web schimbă date.

REST: cel mai comun stil

REST este o convenție larg folosită pentru proiectarea API-urilor web. Fiecare tip de lucru are propriul URL, iar metodele standard spun ce faci cu el. Iată cum ar putea arăta un API REST pentru o aplicație de rezervări:

Există și PUT, care, convențional, înlocuiește o înregistrare întreagă, în timp ce PATCH schimbă doar câmpurile pe care le trimiți.

Coduri de status pe care le vei vedea cel mai des:

Când aplicația ta se strică, codul de status este adesea cel mai rapid indiciu. Un 401 de la un furnizor de plăți înseamnă de obicei o cheie API lipsă sau greșită; un 429 înseamnă că apelezi prea des.

REST nu este singurul stil — există și GraphQL și API-uri în stil RPC — dar REST este ceea ce folosesc cele mai multe servicii și backend-urile construite cu AI.

Un exemplu practic: confirmarea unei rezervări

Când un client rezervă o tunsoare într-o aplicație pentru saloane, pot avea loc mai multe apeluri API în una-două secunde:

1. Pagina de rezervare din browser trimite POST /api/bookings cu serviciul, ora și datele clientului către backend-ul tău.
2. Backend-ul verifică dacă intervalul este liber, salvează rezervarea în baza de date și returnează 201 Created.
3. Backend-ul apelează API-ul unui furnizor de email cu cheia lui secretă: „trimite această confirmare la lena@example.com.”
4. Dacă există un avans, backend-ul cere API-ului furnizorului de plăți să creeze o sesiune de checkout și trimite clientul acolo.
5. Mai târziu, furnizorul de plăți îți apelează aplicația ca să spună că plata a reușit. Acest apel invers este un webhook.

Primii doi pași țin de propriul tău API dintre frontend și backend. Pașii 3–5 sunt API-uri terțe.

Termeni explicați

Greșeli frecvente și idei greșite

• Punerea cheilor secrete în frontend. Orice se află în codul care rulează în browser poate fi văzut de oricine vizitează site-ul. Cheile secrete trebuie să rămână pe server, în variabile de mediu sau secrete.
• Lipirea cheilor în chat. Istoricul chat-ului poate fi stocat. Folosește în schimb funcția de secrete a constructorului și rotește orice cheie pe care ai expus-o.
• Presupunerea că un API este gratuit. Multe API-uri costă per cerere sau per unitate de utilizare — API-urile modelelor AI costă per token. Verifică prețurile și setează limite de cheltuieli. Vezi cum folosești API-urile LLM.
• Lipsa tratării erorilor. Serviciile externe se opresc, expiră și ating limite. Cere mesaje de eroare sensibile și reîncercări.
• Încrederea în browser. API-ul tău trebuie să verifice singur permisiunile. Ascunderea unui buton nu oprește pe cineva să apeleze endpoint-ul direct.
• Folosirea cheilor live în timpul testelor. Folosește cheile din modul test până ești gata să lansezi.

Ce să ceri constructorului tău AI

• „Ce API-uri externe folosește această aplicație și cât costă fiecare?”
• „Apelează API-ul de plăți doar de pe server. Citește cheia dintr-o variabilă de mediu.”
• „Listează fiecare endpoint din API-ul nostru, ce face și cine are voie să-l apeleze.”
• „Verifică pe server că utilizatorul conectat este proprietarul rezervării înainte să o actualizezi sau să o ștergi.”
• „Dacă API-ul de email eșuează, salvează totuși rezervarea și înregistrează eroarea.”
• „Folosește deocamdată modul test al furnizorului.”

API-uri în Mythex

Mythex poate construi propriul tău API — ca parte a unei aplicații web sau ca backend separat, în Node, Python (FastAPI), C# sau Java, care rulează alături de frontend — și poate scrie codul care apelează servicii externe. Adaugi cheile lor ca secrete ale proiectului, nu în chat, iar aplicația ta le poate folosi în previzualizare și după publicare. Documentația are rețete pentru integrarea oricărui API și construirea unui backend REST API.

Întrebări