Cum funcționează cererile, răspunsurile și payload-urile API?
O cerere API este un mesaj trimis de la o aplicație la alta pentru a recupera informații sau a efectua o operațiune suportată.
Aplicația care primește cererea o procesează și, în general, returnează un răspuns HTTP.
Înțelegerea cererilor și răspunsurilor ajută afacerile să configureze, să testeze și să depaneze integrările externe.
Ce conține o cerere API?
În funcție de furnizor, o cerere poate include:
1. Un URL de endpoint.
2. O metodă HTTP.
3. Informații de autentificare.
4. Antete de cerere.
5. Parametrii de interogare.
6. Un corp al cererii.
7. Identificatori pentru înregistrările sau resursele implicate.
Nu fiecare cerere necesită toate aceste componente.
Metode HTTP comune
GET
Utilizată de obicei pentru a recupera informații.
POST
Utilizată frecvent pentru a trimite informații sau a iniția o operațiune.
PUT
Utilizată frecvent pentru a înlocui sau actualiza o resursă.
PATCH
Utilizată frecvent pentru a aplica modificări parțiale.
DELETE
Utilizată frecvent pentru a elimina o resursă.
Comportamentul efectiv este definit de API-ul extern.
Ce este un payload API?
Un payload este datele transportate într-o cerere sau răspuns.
Multe API-uri folosesc JSON, deși sunt posibile și alte formate.
Un payload JSON poate conține câmpuri precum identificatori de clienți, stări ale înregistrărilor, timpi de marcaj sau parametri operaționali.
Ce este un răspuns API?
Un răspuns conține de obicei un cod de stare HTTP și poate include un corp al răspunsului.
Corpul răspunsului poate conține informațiile solicitate, confirmarea unei operațiuni sau detalii despre erori.
Coduri de răspuns HTTP comune
200 — Cererea a fost realizată cu succes.
201 — O resursă a fost creată.
202 — Cererea a fost acceptată pentru procesare, dar procesarea poate să nu fie completă.
204 — Cererea a reușit fără un corp al răspunsului.
400 — Cererea este invalidă.
401 — Autentificarea lipsește sau este invalidă.
403 — Accesul este interzis.
404 — Resursa solicitată nu a fost găsită.
409 — A apărut un conflict.
429 — Cererea a fost limitată prin rată.
500 — Serviciul extern a întâmpinat o eroare internă.
503 — Serviciul este temporar indisponibil.
Acestea sunt semnificațiile comune HTTP. API-urile individuale pot oferi detalii suplimentare.
Înseamnă HTTP 200 întotdeauna că operațiunea de afaceri s-a finalizat corect?
Nu neapărat.
Un răspuns HTTP de succes confirmă că serverul a gestionat cererea conform contractului său API.
Datele returnate și rezultatul de afaceri ulterior ar trebui să fie validate în continuare.
Ce se întâmplă dacă un API returnează informații incomplete?
Revizuiți structura răspunsului furnizorului, permisiunile, câmpurile solicitate, regulile de paginare și disponibilitatea datelor.
Unele API-uri returnează doar câmpuri selectate sau un număr limitat de înregistrări pe cerere.
Ce este paginarea?
Paginarea este un mecanism care împarte colecții mari de înregistrări în grupuri mai mici.
O integrare poate necesita să solicite mai multe pagini pentru a recupera o colecție completă.
Ce este maparea datelor?
Maparea datelor definește modul în care câmpurile dintr-un sistem corespund câmpurilor din altul.
De exemplu, două sisteme pot reprezenta aceleași informații de afaceri folosind nume sau structuri de câmpuri diferite.
Cum ar trebui să validez o operațiune API?
Pasul 1: Confirmați endpoint-ul și metoda HTTP.
Pasul 2: Verificați autentificarea.
Pasul 3: Verificați parametrii necesari.
Pasul 4: Trimiteți o cerere controlată.
Pasul 5: Inspectați răspunsul HTTP.
Pasul 6: Validați informațiile returnate.
Pasul 7: Confirmați rezultatul de afaceri așteptat.
Pasul 8: Revizuiți gestionarea erorilor înainte de utilizarea în producție.
Abordare recomandată
Tratați comunicarea de succes și procesarea de afaceri de succes ca cerințe de validare separate.
Ambele ar trebui confirmate înainte de a se baza pe o integrare API pentru operațiuni importante.