Ce este un API REST — explicat fără jargon

«Vrem să integrăm cu API-ul lor.» Auzi asta de la dezvoltatorul tău, de la eMAG, de la ANAF. Ce înseamnă exact, cât costă și de ce nu poți pur și simplu să copiezi datele manual? Răspunsul e mai simplu decât pare.

Analogia ospătarului

Să zicem că intri într-un restaurant. Tu stai la masă, bucătăria e în spate. Nu mergi tu în bucătărie să-ți iei mâncarea — chemi ospătarul, îi spui ce vrei, el duce comanda în bucătărie și îți aduce farfuria. Ospătarul e API-ul. Tu (clientul) nu ai acces direct la bucătărie (serverul și baza de date). Ospătarul preia comanda într-un format standardizat («o porție de mici la grătar, fără cartofi»), o duce unde trebuie și îți aduce rezultatul.

În software: aplicația ta vrea date de la alt sistem. Nu se conectează direct la baza de date a acelui sistem — ar fi nesigur și imposibil de scalat. Trimite o cerere către un URL specific, primește înapoi un răspuns într-un format pe care îl poate citi. Atât.

Ce înseamnă REST

REST înseamnă Representational State Transfer. E un set de convenții despre cum ar trebui să arate acele cereri și răspunsuri. Nu e o tehnologie — e un stil arhitectural definit în 2000 de Roy Fielding în teza lui de doctorat. Aproape fiecare API public construit în ultimii 15 ani folosește REST.

Cuvântul-cheie în REST e resursă. O resursă e orice entitate cu care lucrezi: un produs, un client, o comandă, o factură. Fiecare resursă are un identificator unic — un URL. De exemplu: https://api.magazintiuroastra.ro/produse/4821 identifică produsul cu ID-ul 4821.

Cele patru operații de bază

REST folosește verbe din protocolul HTTP pentru a spune ce vrei să faci cu o resursă. Sunt patru care acoperă 95% din cazuri:

Aceleași patru verbe, combinate cu URL-uri diferite, formează tot ce face aplicația ta cu date din exterior. Restul e detaliu.

Cum arată un request și un response

Aplicația ta trimite o cerere HTTP. Iată un exemplu concret — preluarea datelor unui produs:

Cererea (request):

GET /produse/4821 HTTP/1.1
Host: api.magazintiuroastra.ro
Authorization: Bearer cheie_secreta

Răspunsul (response):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 4821,
  "nume": "Cremă de față bio",
  "pret": 129.90,
  "moneda": "RON",
  "stoc": 34
}

Formatul din răspuns se numește JSON (JavaScript Object Notation). E text structurat pe care orice limbaj de programare îl poate citi. Nu e nimic mistic — sunt chei și valori despărțite prin virgulă, închise între acolade.

Autentificare — cum știe API-ul cine ești

Un API fără autentificare ar permite oricui să citească sau să modifice datele tale. De aceea aproape fiecare API cere dovada că ai dreptul să accesezi resursa respectivă. Trei metode comune:

• Cheie API (API key) — un șir de caractere pe care îl trimiți în header-ul cererii. Simplu, folosit de Stripe, Google Maps, majoritatea serviciilor SaaS. Generezi cheia din dashboard-ul contului tău.
• OAuth 2.0 — protocolul folosit când un utilizator își dă permisiunea ca aplicația ta să acceseze contul lui din alt serviciu («Conectează-te cu Google»). Folosit de ANAF e-Factura, Facebook, GitHub.
• JWT (JSON Web Token) — un token semnat digital pe care serverul ți-l dă după login. Îl atașezi la fiecare cerere ulterioară. Standard pentru aplicațiile cu cont de utilizator.

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

Dacă ai un magazin online sau o aplicație, folosești probabil deja 5-10 API-uri fără să le numeri:

• Stripe / PayU — procesarea plăților cu cardul. Când clientul apasă «Plătește», site-ul tău trimite datele către API-ul Stripe, care returnează «plată acceptată» sau «refuzată».
• Google Maps — harta de pe pagina de contact sau calculul distanței de livrare. Primește coordonatele GPS și returnează o imagine sau o distanță.
• eMAG Marketplace — sincronizarea stocurilor și prețurilor. Site-ul tău trimite PUT /products/123 cu noul preț, iar eMAG actualizează listația.
• ANAF e-Factura — transmiterea facturilor electronice obligatorii. Aplicația ta generează XML-ul facturii și îl trimite către API-ul ANAF SPV.
• Curier (FAN Courier, DPD, Sameday) — generarea AWB-ului direct din comandă, fără să deschizi portalul curierului.

Când ai nevoie de o integrare API în business-ul tău

1. Vrei să automatizezi o sarcină manuală — dacă angajatul tău copiază comenzi dintr-un sistem în altul de 50 de ori pe zi, o integrare API face asta în 0 secunde, fără erori umane.
2. Vrei să sincronizezi date între două sisteme — stocul din ERP trebuie să se reflecte în magazinul online și pe eMAG simultan, nu mâine dimineață.
3. Adaugi o funcționalitate pe care nu are sens s-o construiești de la zero — plăți, hărți, email tranzacțional, SMS. Le folosești pe ale celor care le-au perfecționat deja.
4. Trebuie să te conformezi unei reglementări — e-Factura ANAF e obligatorie prin API pentru volume peste pragurile stabilite prin OUG 120/2021.

Coduri de status HTTP — ce înseamnă pentru tine

Fiecare răspuns vine cu un cod numeric de 3 cifre. Cele pe care trebuie să le cunoști:

• 200 OK — cererea a reușit, datele sunt în body.
• 201 Created — resursa a fost creată (după POST).
• 400 Bad Request — cererea ta e greșit formatată (câmp lipsă, valoare invalidă).
• 401 Unauthorized — token-ul lipsește sau a expirat.
• 403 Forbidden — ai token, dar nu ai permisiune pentru resursa asta.
• 404 Not Found — resursa nu există (produsul 4821 a fost șters).
• 429 Too Many Requests — ai trimis prea multe cereri într-un timp scurt (rate limiting).
• 500 Internal Server Error — problema e la ei, nu la tine. Încearcă din nou mai târziu.

O integrare solidă nu presupune doar să trimiți cererea, ci să tratezi diferit fiecare din aceste coduri: retry la 500 și 429, re-autentificare la 401, eroare de validare la 400.

Cât costă o integrare API

Depinde de complexitatea API-ului cu care te integrezi și de cât de robustă trebuie să fie gestionarea erorilor. Intervale reale:

Cel mai mare factor de cost nu e API-ul în sine, ci gestionarea cazurilor de eroare: ce se întâmplă când serverul lor pică, când token-ul expiră, când formatul de răspuns se schimbă fără avertizare. O integrare făcută bine tratează toate aceste cazuri. Una făcută rapid le ignoră — și le plătești în producție, sub formă de comenzi pierdute sau facturi netransmise.

Citește în continuare

• Servicii: Integrări API
• Ghid: Integrare API ANAF e-Factura 2026
• Dicționar IT pentru non-tehnici