API și FastAPI pe înțelesul tuturor

API este modul prin care programele comunică între ele. Unul cere, celălalt răspunde. Luând ca exemplu un marketplace, vedem din ce se compune o cerere, cum se citește un răspuns JSON și ce trebuie verificat când Claude Code conectează o sursă externă de date. La final lămurim pe scurt unde intră în joc FastAPI.

Ce este un API pe înțelesul tuturor

API (Application Programming Interface) este o interfață de programare. Ea definește operațiile disponibile și regulile prin care pot fi apelate. Nu doar aplicațiile separate au API, ci și bibliotecile, sistemul de operare, browserul. Prin el, un program poate cere altui program (sau unei părți a lui) să facă ceva și poate primi rezultatul. Aici vorbim în principal despre API-uri de rețea, la care se ajunge printr-o adresă.

Imaginați-vă un restaurant. Ca client, nu intrați în bucătărie și nu îi explicați bucătarului cum să gătească - îi spuneți ospătarului ce vreți din meniu, iar el duce comanda la bucătărie și vă aduce felul gata. API-ul este ospătarul. Programul-client plasează comanda prin el, iar bucătăria (celălalt program) o execută. Nu e nevoie să știți cum e organizat totul pe dinăuntru - e suficient să cunoașteți meniul și să înțelegeți ce puteți cere și ce veți primi înapoi.

În esență, API-ul este un contract: "mă poți apela în felul acesta, iar drept răspuns îți returnez un astfel de rezultat".

Mai există și un scurt clip amuzant în engleză - "How API work". E o ilustrare a aceleiași idei, nu o explicație a temei. Tot ce e necesar găsiți în textul de mai jos.

Cererea și răspunsul: exemplul unui marketplace

Imaginați-vă un marketplace în care un furnizor trimite produse din propriul program. Transferul a mii de poziții prin butoanele site-ului e incomod, așa că marketplace-ul pune la dispoziție operații API programatice. De exemplu, POST /products adaugă un produs, iar GET /reports returnează un raport.

Adresa unei operații disponibile se numește endpoint. Pentru a înțelege cererea, se ține cont și de adresă, și de metoda HTTP. GET /products și POST /products pot executa acțiuni diferite. GET se folosește de obicei pentru citire, POST - pentru trimiterea datelor spre prelucrare.

Datele se transmit adesea în format JSON. Acoladele grupează câmpurile unui obiect, șirurile se scriu între ghilimele, iar o listă de obiecte - între paranteze drepte:

{
  "name": "Lampă de birou",
  "price": 15000,
  "count": 350
}

Clientul trimite cererea, serverul o prelucrează și returnează răspunsul. Mai jos e o schemă simplificată a schimbului, nu un pachet HTTP complet:

POST /products
{ "name": "Lampă de birou", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created - statusul răspunsului, iar JSON-ul de dedesubt - corpul cu rezultatul. Într-un API real, documentația indică endpoint-ul, metoda, parametrii obligatorii, antetele, forma răspunsului și erorile posibile. E mai sigur să începeți cu un singur obiect de test, nu cu setul complet de date.

Frontend, backend și API-ul dintre ele

API-ul nu servește doar la conectarea unor aplicații diferite. Adesea o singură aplicație e formată pe dinăuntru din două programe, iar acestea comunică tot printr-un API.

Frontend-ul este partea aplicației cu care lucrați în browser. Aici intră butoanele, imaginile, meniurile, formularele și comportamentul paginii. Logica lui de program se scrie de obicei în JavaScript. El poate atât să facă singur calcule complexe, cât și să apeleze serverul când sunt necesare date sau acțiuni pe partea serviciului.

Backend-ul este partea de server a aplicației. Ea procesează plățile, salvează comenzile, verifică accesul, caută produsele. În timpul dezvoltării, serverul poate rula pe computerul dumneavoastră, iar după publicare - pe hosting. Utilizatorul nu primește codul lui sursă odată cu pagina. Browserului îi ajung doar răspunsurile la cereri.

Cum comunică ele? Prin același API. Backend-ul pune la dispoziție rute nu doar furnizorilor externi, ci și propriului frontend:

• ați deschis pagina - frontend-ul apelează ruta /products/list, backend-ul returnează lista de produse, frontend-ul le afișează frumos;
• ați apăsat "cumpără" - frontend-ul trimite datele către ruta /orders, backend-ul înregistrează comanda.

Deci prin API pot comunica atât aplicații diferite, cât și părți ale aceleiași aplicații. În această schemă, browserul trimite cererea, backend-ul lucrează cu datele și returnează rezultatul. Baza de date nu trebuie neapărat să fie accesibilă browserului direct.

Cererea din browser

Mai sus am spus că frontend-ul "apelează ruta" backend-ului. Să vedem cum arată asta în cod. Browserul are pentru asta o funcție integrată, fetch. Ea trimite o cerere HTTP la adresa dorită și returnează răspunsul. Corpul răspunsului vine de obicei în JSON, iar el se transformă în obiect prin metoda .json().

Să luăm un catalog de locale-uri - combinații de limbă și setări regionale. Presupunem că backend-ul știe deja să returneze lista la adresa /locales, iar frontend-ul trebuie să o afișeze. De exemplu, serverul returnează:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Cum vine răspunsul

Fragmentul de mai jos rulează în interiorul unui handler asincron al paginii. El obține datele; afișarea tabelului nu e prezentată aici.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Acum locales conține datele pentru tabel

Verificăm res.ok înainte de a citi datele. O eroare HTTP precum 404 sau 500 nu face, de la sine, ca fetch să se încheie cu o excepție. Separat, poate eșua cererea de rețea în sine sau parsarea JSON-ului. Eroarea dintr-un astfel de fragment trebuie prinsă de codul paginii, care să afișeze un mesaj clar. Sunt cauze diferite, deși în toate cazurile utilizatorul n-a reușit să obțină datele. Mai multe detalii - în ghidul MDN despre fetch.

Sunt câteva detalii mărunte, ușor de scăpat din vedere:

• implicit, fetch face GET - o cerere de obținere a datelor. Alte operații se stabilesc prin metodă; de exemplu, marketplace-ul nostru primește un produs nou prin POST;
• adresa /locales este relativă. Pe o pagină HTTP obișnuită, ea vizează rădăcina aceleiași origini. Originea e definită de schemă, host și port; serverul trebuie să aibă o astfel de rută;
• fetch și .json() nu returnează rezultatul imediat, de aceea în fața lor se scrie await - "așteaptă răspunsul".

Dacă deschideți HTML-ul ca fișier prin file://, adresa /locales nu va deveni adresa serverului dumneavoastră HTTP. Pentru acest exemplu, pagina se deschide printr-un server pe care e implementată ruta respectivă. Fișierul HTML în sine nu creează o astfel de rută.

Frontend-ul și API-ul pot fi pe origini diferite. Atunci, pentru a citi răspunsul din browser, serverul API trebuie să permită accesul necesar prin CORS. E un mecanism de acces cross-site, nu numele oricărei erori de rețea. Plasarea paginii și a API-ului pe aceeași origine simplifică exemplul, dar nu e obligatorie pentru toate aplicațiile. Detalii găsiți în descrierea CORS pe MDN.

Cine răspunde browserului

Cine răspunde la fetch("/locales")? Backend-ul, iar el nu trebuie neapărat să fie în Python cu FastAPI. API-ul este o înțelegere între programe, nu un limbaj anume. Același endpoint se poate scrie în Node.js, Go sau Java. De exemplu, în handler-ul unui server Node.js se poate returna un array locales pregătit dinainte. Mai jos e doar un fragment de handler, nu un server complet:

// req și res sunt obținute de handler, locales e pregătit dinainte
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Din exterior, e tot aceeași cerere HTTP GET /locales, iar în răspuns - statusul 200 și JSON. Frontend-ul nu are nevoie să știe în ce e scris backend-ul. Îi trebuie adresa, regulile cererii și formatul răspunsului.

Ce tipuri de API există

API-urile pot fi împărțite comod după două criterii:

• locale și de rețea - de exemplu, API-ul unei biblioteci se apelează din codul programului, iar un API de rețea se accesează prin rețea. Rețeaua poate fi și internă, fără internet deschis;
• publice și interne - cele publice sunt destinate dezvoltatorilor externi, cele interne leagă părțile sistemului. Un API public poate cere și el înregistrare, plată și permisiuni.

API-urile web folosesc adesea HTTP - protocolul cererilor și răspunsurilor. REST, al cărui nume îl veți întâlni în documentație, descrie o abordare de construire a API-urilor; nu orice API HTTP respectă automat principiile REST. Deocamdată e mai util să învățați să citiți codul de status din răspuns:

• 200 - totul e în regulă;
• 201 - creat (de exemplu, un obiect nou după POST);
• 404 - negăsit;
• 401 - cererea nu conține date de autentificare valide;
• 429 - prea multe cereri;
• 500 - eroare internă de server.

Deocamdată nu e nevoie să intrați în detalii. Important e să prindeți ideea schimbului de cereri și răspunsuri. Pentru moment e suficient.

De ce are nevoie serviciul de o cheie de acces

Multe servicii cer mai întâi să obțineți o cheie API - un șir legat de contul sau proiectul dumneavoastră. Se transmite în modul indicat în documentație, adesea într-un antet al cererii. Serviciul verifică accesul și poate ține evidența numărului de cereri pe care le-ați făcut. La alte integrări veți întâlni cuvântul token. Are un rol asemănător, dar modul de obținere, durata de valabilitate și drepturile pot diferi.

Fără acces valid, cererea nu se va executa; de exemplu, serverul poate răspunde cu 401. Depășirea limitei de frecvență a cererilor se marchează adesea cu codul 429. Sensul exact al răspunsului și volumele permise se verifică în documentația serviciului respectiv. Există și surse deschise care nu au nevoie deloc de cheie.

Unde se caută un API gata făcut

Prin API se integrează în aplicații hărți, prognoza meteo, plăți și livrare. Documentația deschisă ajută să înțelegeți posibilitățile serviciului încă înainte de conectare. E mai bine să porniți chiar de la sarcină. Stabiliți ce date vă trebuie, cât de des trebuie actualizate și ce intenționați să faceți cu ele.

Pentru căutare, e util să vă uitați la Postman Public API Network, un catalog de API-uri și exemple de cereri. Exemplul găsit e doar un punct de plecare. Adresa, formatul, accesul și limitările le verificați oricum în documentația oficială a proprietarului serviciului.

Unde intră în joc FastAPI

FastAPI este unul dintre framework-urile pentru crearea de API-uri și servere web în Python. Poate lega un endpoint de codul dumneavoastră de server, poate primi o cerere și returna un răspuns JSON. FastAPI vă trebuie când vă creați propriul backend Python; ca să folosiți un API gata făcut, nu e nevoie să-l studiați. La nivelul 7 e suficient să recunoașteți numele și să înțelegeți această graniță.

Cum funcționează asta împreună cu Claude Code

Cu aceste noțiuni e mai ușor să evaluați munca agentului. El poate citi documentația API-ului altcuiva, poate scrie o cerere de client sau poate crea API-ul dumneavoastră în FastAPI. Pentru dumneavoastră contează să vedeți traseul concret de la cerere la datele de pe pagină. Cine trimite cererea, cine răspunde și cum se prelucrează răspunsul?

De exemplu, pentru un radar de cutremure există feed-ul public GeoJSON al USGS. Adresa listei pentru ultima oră:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Mai jos e un mic exemplu didactic despre structura răspunsului, cu un eveniment fictiv și un set redus de câmpuri. Nu sunt datele actuale ale USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Punct didactic" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

În features se află un array de evenimente. Calea features[0].properties.mag duce la magnitudinea primului. Indicele 0 înseamnă primul element al array-ului. Coordonatele vin în ordinea "longitudine, latitudine, adâncime în kilometri". Agentul poate folosi magnitudinea pentru dimensiunea punctului, iar coordonatele - pentru poziția lui. Dacă array-ul e gol, nu există un prim element; dacă magnitudinea e null, e o valoare necunoscută, nu o forță zero a evenimentului.

Rămâne de decis ce se afișează după cerere:

Cât timp cererea rulează, pagina poate afișa un indicator de încărcare. Pentru a verifica diferitele situații, e util să folosiți răspunsuri didactice. Astfel nu va trebui să așteptați un eșec real al serviciului sau un nou cutremur.

Sarcina pentru Claude Code poate suna acum așa:

Conectează la pagină datele din API-ul indicat.
Verifică mai întâi documentația oficială: adresa, metoda,
formatul răspunsului și condițiile de acces. Arată ce câmpuri folosești.
Tratează încărcarea, lista goală și eroarea de actualizare.
Dacă folosești date vechi după un eșec, marchează asta pe pagină.
Nu pune cheia secretă în codul de client.
Verifică rezultatul și spune-mi ce stări ai reușit să testezi.

După ce agentul a terminat, uitați-vă la cererea propriu-zisă și la rezultatul verificării, nu doar la imaginea finală. Faceți separat diferența dintre accesul agentului și accesul paginii. MCP poate conecta un instrument la Claude Code, dar aplicația publicată are nevoie de propria integrare. Sesiunea închisă a agentului nu trebuie să oprească cererile site-ului, dacă acestea sunt implementate în aplicația propriu-zisă.