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

«Vrem să integrăm cu API-ul lor.» O auziți de la dezvoltator, de la eMAG, de la ANAF. Ce înseamnă exact, cât costă și de ce nu puteți pur și simplu să copiați datele manual? Răspunsul e mai simplu decât pare.

Analogia ospătarului

Să zicem că intrați într-un restaurant. Stați la masă, bucătăria e în spate. Nu mergeți în bucătărie să vă luați mâncarea: chemați ospătarul, îi spuneți ce doriți, el duce comanda în bucătărie și vă aduce farfuria. Ospătarul e API-ul. Dumneavoastră (clientul) nu aveți 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 vă aduce rezultatul.

În software: aplicația dumneavoastră are nevoie de date de la alt sistem. Nu se conectează direct la baza de date a acelui sistem, pentru că 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, ci 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 lucrați: 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 doriți să faceți 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 dumneavoastră cu date din exterior. Restul e detaliu.

Cum arată un request și un response

Aplicația dumneavoastră 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 sunteți

Un API fără autentificare ar permite oricui să citească sau să modifice datele dumneavoastră. De aceea aproape fiecare API cere dovada că aveți dreptul să accesați resursa respectivă. Trei metode comune:

• Cheie API (API key): un șir de caractere trimis în header-ul cererii. Simplu, folosit de Stripe, Google Maps și majoritatea serviciilor SaaS. Cheia se generează din dashboard-ul contului.
• OAuth 2.0: protocolul folosit când un utilizator își dă permisiunea ca aplicația dumneavoastră 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 îl emite după login. Aplicația îl atașează la fiecare cerere ulterioară. Standard pentru aplicațiile cu cont de utilizator.

Exemple de API-uri pe care le folosiți zilnic

Dacă aveți un magazin online sau o aplicație, folosiți probabil deja 5-10 API-uri fără să le numărați:

• Stripe / PayU: procesarea plăților cu cardul. Când clientul apasă «Plătește», site-ul 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 trimite PUT /products/123 cu noul preț, iar eMAG actualizează listația.
• ANAF e-Factura: transmiterea facturilor electronice obligatorii. Aplicația generează XML-ul facturii și îl trimite către API-ul ANAF SPV. Endpoint-urile și exemplele de cod sunt în ghidul nostru pentru API-ul ANAF e-Factura.
• Curier (FAN Courier, DPD, Sameday): generarea AWB-ului direct din comandă, fără să deschideți portalul curierului.

Când aveți nevoie de o integrare API în firmă

1. Doriți să automatizați o sarcină manuală: dacă un angajat 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. Doriți să sincronizați date între două sisteme: stocul din ERP trebuie să se reflecte în magazinul online și pe eMAG simultan, nu mâine dimineață.
3. Adăugați o funcționalitate pe care nu are sens s-o construiți de la zero: plăți, hărți, email tranzacțional, SMS. Le folosiți pe ale celor care le-au perfecționat deja.
4. Trebuie să vă conformați 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 dumneavoastră

Fiecare răspuns vine cu un cod numeric de 3 cifre. Cele pe care e bine să le cunoașteți:

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

O integrare solidă nu presupune doar trimiterea cererii, ci tratarea diferită a 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 vă integrați ș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ă în grabă le ignoră, iar costul apare în producție, sub formă de comenzi pierdute sau facturi netransmise.