Un API definește modul în care un program cere date sau o acțiune de la altul. Astfel, un site poate crea un contact în CRM, un serviciu de plăți poate comunica rezultatul, iar o aplicație mobilă poate citi soldul unui cont. Un API util nu este doar o colecție de adrese: este un contract pentru date, permisiuni, erori și schimbări.
Proiectați pornind de la acțiuni reale
Identificați evenimentele și înregistrările de care integrarea are nevoie. Dați nume clare operațiilor și returnați doar informațiile necesare. Descrieți intrările acceptate, răspunsurile posibile și erorile. Documentația și exemplele trebuie să corespundă serviciului lansat, nu unei specificații mai vechi.
Securitatea aparține contractului
Autentificați apelantul și verificați dreptul asupra fiecărei înregistrări concrete, nu doar rolul general. Limitați frecvența cererilor și validați toate datele primite. Păstrați cheile secrete pe servere de încredere. Înregistrați operațiile care modifică plăți, permisiuni sau date ale clienților.
Luați în calcul rețele nesigure
O cerere poate expira deși celălalt serviciu a terminat deja operația. Faceți scrierile importante idempotente: repetarea nu trebuie să dubleze comenzi ori plăți. Stabiliți limite de timp și reguli de reluare. Pentru evenimente, păstrați istoricul livrărilor și permiteți reprocesarea celor eșuate.
Pregătiți schimbarea
Clienții și serviciile sunt rareori actualizate simultan. Preferați schimbări compatibile, versiuni explicite pentru cele care rup compatibilitatea și monitorizați cine mai folosește comportamentul vechi. Un API bine întreținut permite evoluția produsului fără câte un remediu fragil pentru fiecare integrare.
