Anatomia unei integrări — API-uri și integrarea serviciilor externe

Aproape orice aplicație modernă vorbește cu servicii externe: plăți (Stripe), email (Postmark), curierat, hărți, SMS, AI. O integrare bună nu înseamnă „am chemat endpointul o dată și a mers" — înseamnă cum se comportă aplicația ta când serviciul celălalt e lent, întoarce o eroare, își schimbă formatul sau te limitează.

Ce citești din documentație, înainte de a scrie cod

Cum te autentifici (cheie, OAuth, semnătură).
Ce limite de rată are (câte cereri pe minut/zi).
Ce coduri de eroare întoarce și ce înseamnă fiecare.
Ce structură are răspunsul (și cum semnalează erorile în corp).
Cum notifică evenimente asincrone (webhooks).
Dacă are un mediu de sandbox pentru teste.

Izolează integrarea

Nu împrăștia apeluri către serviciul extern prin tot codul. Creezi o clasă client (`StripeClient`, `CurierClient`) care e singurul loc care știe de acel serviciu. Restul aplicației vorbește cu clientul tău. Așa poți schimba furnizorul, îl poți testa cu mock-uri, și tratezi erorile într-un singur loc.

Timeout, mereu

Fiecare apel HTTP către un serviciu extern are un timeout explicit (5-15 secunde de obicei). Fără el, dacă serviciul „atârnă", cererea ta atârnă cu el, ținând ocupat un worker.

Gândește la eșec de la început

Pentru fiecare integrare, întreabă: ce se întâmplă dacă apelul eșuează? Blochează utilizatorul? Se poate reîncerca mai târziu (pune-l pe coadă)? Are un fallback? Răspunsul modelează unde pui apelul (sincron în cerere vs. job asincron).

Exercițiu

Alege un serviciu extern pe care l-ai folosi (plăți, email, SMS). Citește-i documentația și notează: metoda de autentificare, limitele de rată, 3 coduri de eroare posibile, dacă are webhooks și sandbox. Schițează o clasă client cu 2-3 metode.

Greșeli frecvente

Apeluri către serviciul extern împrăștiate în controllere și modele.
Fără timeout — o cerere lentă la ei blochează worker-ul tău.
Presupui că apelul reușește mereu — nicio cale de eroare.
Nu citești despre limitele de rată până nu le lovești în producție.

De reținut

Citește documentația: auth, rate limits, erori, format, webhooks, sandbox.
Izolează fiecare integrare într-o clasă client.
Timeout explicit pe fiecare apel.
Proiectează pentru eșec de la început.

Pe scurt

O integrare e cum se comportă aplicația ta când celălalt serviciu are o zi proastă. Izoleaz-o, pune timeout, planifică eșecul.