API-urile: cum comunică aplicațiile între ele

Un API (Application Programming Interface, adică interfață de programare a aplicațiilor) este un set de reguli prin care un program poate cere informații sau servicii de la alt program, într-un format convenit dinainte. Când aplicația de vreme îți arată prognoza, când un magazin online îți calculează costul livrării sau când te autentifici pe un site cu un cont existent, în fundal mai multe programe își trimit cereri și răspunsuri prin API-uri.

Ideea centrală este separarea: programul care cere nu trebuie să știe cum funcționează pe dinăuntru programul care răspunde. Trebuie doar să respecte regulile de comunicare. Astfel, o aplicație mică poate folosi servicii uriașe, cum ar fi hărți, plăți sau traduceri, fără să le construiască singură. Mai jos afli cum arată concret o astfel de comunicare și ce reguli o fac sigură.

O analogie: ghișeul cu formular standard

Cea mai simplă cale de a înțelege un API este să te gândești la un ghișeu de la o instituție. Nu intri în arhivă să cauți singur dosarul; completezi un formular standard, îl dai la ghișeu și primești înapoi un document, sau o explicație de ce cererea nu poate fi rezolvată.

Analogia arată și de ce API-urile sunt utile pentru siguranță: cine cere vede doar ghișeul, nu are acces direct la arhivă. Serviciul decide exact ce informații ies și pentru cine.

Cum arată o cerere și un răspuns

Pe web, cele mai multe API-uri folosesc HTTP, același protocol prin care browserul încarcă paginile. O cerere are câteva părți standard, iar răspunsul vine într-un format ușor de citit de programe.

Părțile unei cereri

1. Metoda, care spune ce vrei să faci (citești, creezi, modifici, ștergi).
2. Adresa (URL-ul) endpointului, de exemplu adresa resursei „comenzi” a unui magazin.
3. Antetele (headers), cu informații suplimentare: cine ești, ce format accepți.
4. Corpul (body), opțional, cu datele trimise, de exemplu conținutul unei comenzi noi.

Metodele HTTP cele mai folosite

Formatul JSON

Răspunsul vine de cele mai multe ori în JSON (JavaScript Object Notation), un format text cu perechi „nume: valoare”, ușor de citit atât de oameni, cât și de programe. O prognoză meteo ar putea conține, de exemplu, numele orașului, temperatura, umiditatea și o listă cu valorile pentru zilele următoare, fiecare cu eticheta ei. Formatul nu depinde de limbajul de programare, de aceea un server scris într-un limbaj poate vorbi fără probleme cu o aplicație de telefon scrisă în altul.

Codurile de stare: cum spune serverul dacă a reușit

Fiecare răspuns HTTP începe cu un cod de stare de trei cifre, care arată rezultatul cererii înainte ca programul să citească datele. Prima cifră indică familia rezultatului.

• 2xx – succes: 200 înseamnă „în regulă”, 201 înseamnă „resursa a fost creată”.
• 3xx – redirecționare: resursa se află la altă adresă.
• 4xx – eroare a celui care cere: 400 (cerere greșită), 401 (neautentificat), 403 (fără drept de acces), 404 (resursa nu există), 429 (prea multe cereri).
• 5xx – eroare a serverului: 500 (eroare internă), 503 (serviciu temporar indisponibil).

Codul 404 îl cunoști probabil din browser, când o pagină nu mai există. În API-uri, aceleași coduri permit programelor să reacționeze automat: să reîncerce mai târziu la un 503, să ceară reautentificarea la un 401 sau să încetinească la un 429.

Sfat: Dacă o aplicație îți afișează un mesaj de eroare cu un cod de tipul 429 sau 503, de cele mai multe ori problema este temporară și ține de server. Așteaptă câteva minute înainte să reîncerci, în loc să apeși repetat același buton.

Stilurile de API: REST, GraphQL, RPC și webhookuri

Nu toate API-urile sunt construite la fel. Câteva stiluri s-au impus, fiecare cu avantajele lui, iar alegerea depinde de tipul aplicației și de cantitatea de date transmise.

REST

REST este stilul cel mai răspândit pe web. Organizează totul în resurse (utilizatori, comenzi, produse), fiecare cu o adresă proprie, și folosește metodele HTTP standard pentru operații. Este simplu, previzibil și ușor de testat. Un dezavantaj este că uneori ai nevoie de mai multe cereri pentru a aduna toate datele unei pagini.

GraphQL

GraphQL permite clientului să ceară exact câmpurile de care are nevoie, într-o singură cerere, printr-un limbaj de interogare. Este util pentru aplicații cu ecrane complexe, care adună date din multe surse, dar e mai complicat de construit și de protejat pe server.

RPC

Stilurile RPC (apel de procedură la distanță) tratează API-ul ca pe o listă de funcții: „calculează”, „trimite”, „verifică”. Variantele moderne sunt foarte rapide și se folosesc des în comunicarea internă dintre serviciile unei aplicații mari din cloud.

Webhookuri: API-ul care te anunță el

În modelele de mai sus, clientul întreabă și serverul răspunde. Webhookul inversează direcția: serviciul trimite el o cerere spre adresa ta atunci când se întâmplă ceva, de exemplu când o plată a fost confirmată. Astfel nu mai este nevoie să întrebi la fiecare minut „s-a întâmplat ceva?”. Același principiu stă la baza notificărilor descrise în Sincronizarea datelor între dispozitive: cum funcționează.

Exemple de API-uri pe care le folosești zilnic

Aproape fiecare aplicație modernă este un ansamblu de servicii legate prin API-uri, unele interne, altele de la furnizori externi. Câteva situații obișnuite:

• Aplicația de vreme cere prognoza de la serviciul unui furnizor de date meteo, nu o calculează singură.
• Hărțile dintr-un site de rezervări sunt încărcate de la un serviciu de cartografiere.
• Plata cu cardul pe un site trimite datele către un procesator de plăți, prin API; magazinul primește doar confirmarea.
• Autentificarea cu un cont existent folosește standardul OAuth, prin care un site primește permisiunea limitată de a-ți citi, de exemplu, numele și adresa de e-mail, fără să-ți afle parola.
• Asistenții de inteligență artificială integrați în alte aplicații trimit textul spre un model de limbaj prin API, după mecanismele din ghidul despre modelele de limbaj.
• Curierii oferă API-uri prin care magazinele generează automat AWB-uri și urmăresc coletele.

Open banking și directiva PSD2

Un exemplu cu impact direct în România este open banking. Directiva europeană privind serviciile de plată, cunoscută ca PSD2, obligă băncile să permită, cu acordul clientului, accesul unor furnizori autorizați la informațiile despre cont și inițierea de plăți, prin interfețe securizate. Așa funcționează aplicațiile care îți arată într-un singur loc conturile de la mai multe bănci. Supravegherea instituțiilor de plată din România revine Băncii Naționale a României (BNR); înainte de a conecta un cont bancar la o aplicație, verifică dacă furnizorul este autorizat.

Securitatea API-urilor

Un API deschide o ușă spre datele și funcțiile unui serviciu, așa că trebuie păzit cu aceeași atenție ca orice ușă. Măsurile de bază sunt autentificarea, autorizarea, criptarea și limitarea cererilor.

Cheile API sunt ca parolele

O cheie API este un șir lung de caractere care identifică programul care face cererea. Oricine o are poate folosi serviciul în numele tău, inclusiv pe costul tău, dacă serviciul este plătit.

Atenție: Nu pune niciodată chei API în codul publicat, în capturi de ecran sau în mesaje trimise pe chat. Păstrează-le în locuri dedicate, cu acces restrâns, și schimbă-le imediat dacă bănuiești că au fost expuse. Aceleași principii se aplică parolelor, după cum arată Parolele puternice și managerele de parole explicate.

Tokenurile moderne au o durată de viață scurtă și drepturi limitate: chiar dacă unul este furat, poate fi folosit puțin timp și doar pentru operațiile permise. Pentru conturile umane care administrează API-uri, autentificarea în doi pași este obligatorie în practică.

API-urile în cloud și în arhitectura aplicațiilor

În cloud, aproape totul se controlează prin API-uri: pornirea unei mașini virtuale, crearea unei baze de date, încărcarea unui fișier sau configurarea rețelei. Interfața grafică pe care o vezi în browser este, de multe ori, doar un client care trimite cereri către aceleași API-uri. Modelele de servicii cloud sunt explicate în IaaS, PaaS și SaaS: diferențele explicate simplu, iar contextul general în ghidul despre cloud computing.

Microserviciile

Aplicațiile mari sunt adesea împărțite în microservicii: programe mici, fiecare cu o singură responsabilitate (plăți, coș de cumpărături, recomandări), care comunică între ele prin API-uri. Avantajul este că fiecare parte poate fi modificată și scalată separat. Dezavantajul este că o cerere a utilizatorului poate trece prin zeci de servicii, iar o problemă într-unul îi poate afecta pe ceilalți.

Versiunile și documentația

Un API public este un contract: alte programe depind de forma lui exactă. De aceea furnizorii îl versionează (versiunea 1, versiunea 2) și anunță din timp schimbările care pot strica integrările existente. Documentația descrie fiecare endpoint, parametrii, formatele și erorile posibile; există și formate standardizate de descriere, care permit generarea automată a documentației și a codului de test.

Ideile principale despre API-uri

Un API este ghișeul prin care un program cere servicii altui program, după reguli clare, fără acces la mecanismele lui interne. Pe web, cererile folosesc HTTP, cu metode precum GET și POST, iar răspunsurile vin în JSON, însoțite de coduri de stare. Stilurile diferă, de la REST la GraphQL și webhookuri, dar principiile de securitate rămân aceleași: identificare, permisiuni minime, criptare și limite.

De reținut:

• API-ul separă cine cere de cine răspunde și protejează datele interne;
• endpointul este adresa, metoda spune ce vrei să faci, JSON este formatul obișnuit;
• codurile 2xx înseamnă succes, 4xx greșeala clientului, 5xx problema serverului;
• webhookurile anunță singure evenimentele, fără interogări repetate;
• cheile API se păstrează ca parolele și se schimbă imediat dacă au fost expuse.