Postman: ce este, testarea API și lucrul cu cererile

Ce este Postman și funcțiile cheie

Postman este o platformă pentru dezvoltarea și testarea API, disponibilă ca aplicație desktop (Windows, macOS, Linux) și versiune web. Creat inițial ca extensie pentru Chrome în 2012, Postman s-a transformat într-un ecosistem complet cu suport pentru monitorizare, mock-server și generare de cod client.

Formate de cereri și răspunsuri

Postman acceptă toate metodele HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Corpul cererii poate fi în formatele JSON, XML, form-data, x-www-form-urlencoded și binary. Răspunsul este afișat cu evidențierea sintaxei, Pretty-print și posibilitatea de vizualizare a anteturilor brute.

Suport pentru autentificare

Tipurile de autentificare integrate includ Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, API Key și AWS Signature. Postman adaugă automat antetul Authorization conform tipului selectat, ceea ce accelerează testarea endpointurilor protejate fără copierea manuală a tokenurilor.

Interfața Postman și navigarea

Interfața Postman constă din panoul lateral (Collections, APIs, Environments), zona de lucru (Request Builder/Response Viewer) și panoul inferior (Console, Runner). Filiera Params permite editarea parametrilor query din URL în formă tabelară, iar filiera Headers — gestionarea anteturilor HTTP.

Postman Console

Console (View → Show Postman Console) înregistrează toate cererile și răspunsurile de rețea în ordine cronologică, inclusiv redirecționările intermediare și anteturile. Este un instrument indispensabil la depanarea fluxurilor OAuth complexe și a lanțurilor de redirecționări, când Response Viewer standard afișează doar rezultatul final.

Workspaces și lucrul în echipă

Postman acceptă spații de lucru de echipă (Workspaces) cu versionarea colecțiilor prin Fork și Merge. Membrii echipei pot comenta cererile, propune modificări și sincroniza colecțiile în timp real. Public Workspace permite publicarea documentației API pentru dezvoltatori externi.

Crearea și trimiterea cererilor HTTP

Cererea de bază în Postman se creează prin selectarea metodei HTTP și introducerea URL în bara de adrese. După trimitere, răspunsul este afișat în panoul inferior cu codul de stare, timpul de execuție și dimensiunea. Parametrii cererii sunt codificați automat la introducere.

Variabile dinamice și snippet-uri

În URL și corpul cererii pot fi folosite variabile dinamice în formatul {`{`}}$variable${`}`}. Variabilele integrate {`{`}$guid${`}`}, {`{`}$timestamp${`}`} și {`{`}$randomInt${`}`} generează valori unice pentru fiecare cerere. Snippet-urile de cod sunt disponibile prin butonul Code (), care generează o cerere echivalentă în cURL, Python, JavaScript, Kotlin, Swift și alte limbaje.

// Exemplu de script în Pre-request: generarea semnăturii HMAC
const timestamp = Date.now().toString();
const secret = pm.environment.get("api_secret");
const hash = CryptoJS.HmacSHA256(timestamp, secret);
pm.request.headers.add({
    key: "X-Signature",
    value: hash.toString()
});

Colecții și variabile de mediu

Colecțiile sunt grupuri de cereri conexe, unite pe proiect sau modul funcțional. Fiecare colecție poate conține subfoldere, anteturi comune și scripturi Pre-request, care se execută înaintea fiecărei cereri din colecție. Ordinea cererilor se setează prin tragere.

Variabile de mediu și variabile globale

Postman acceptă cinci niveluri de variabile: global, collection, environment, data și local. Prioritatea rezolvării conflictelor — de la locale la globale. Fișierele Environment conțin perechi cheie-valoare pentru diferite medii: development, staging, production. Comutarea mediului schimbă automat toate URL-urile și tokenurile.

Automatizarea testării API prin scripturi

Postman permite scrierea testelor în JavaScript în filiera Tests, care se execută după primirea răspunsului. Testele verifică codul de stare, corpul răspunsului, anteturile și timpul de execuție. Rezultatele sunt afișate în panoul Test Results cu indicare colorată a trecerii.

Biblioteca pm și înlănțuirea cererilor

Obiectul pm oferă metode pentru lucrul cu răspunsul: pm.response, pm.expect, pm.variables. Înlănțuirea cererilor se realizează prin salvarea datelor din răspunsul unei cereri într-o variabilă și folosirea ei în următoarea. Aceasta este baza pentru construirea testelor de integrare și verificarea logicii de business prin succesiune de apeluri API.

// Test: verificarea structurii răspunsului și salvarea tokenului
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set("auth_token", json.data.token);

Collection Runner și Newman

Collection Runner execută toate cererile colecției secvențial, efectuând teste la fiecare pas. Newman — versiunea de consolă a Postman pentru pipeline-uri CI/CD (Jenkins, GitHub Actions, GitLab CI). Newman exportă raportul în formatele JSON, JUnit și HTML pentru integrare cu sistemele de monitorizare.

Lucrul cu GraphQL și WebSocket

Cererile GraphQL în Postman se trimit prin POST către un singur endpoint cu corp în format JSON. Filiera GraphQL (Beta) oferă un editor vizual cu evidențierea sintaxei, completare automată a câmpurilor și schemă. Variabilele cererii sunt transmise într-un panou separat Variables.

Testarea WebSocket și Socket.IO

Postman acceptă conexiuni WebSocket printr-o interfață separată cu panou de mesaje. Se pot trimite mesaje text și binare, vizualiza istoricul conexiunii și reconecta automat la întrerupere. Clientul Socket.IO funcționează în mod de compatibilitate cu protocolul Engine.IO.

// Test WebSocket în Postman prin pm API
const ws = new WebSocket("wss://echo.websocket.org");
ws.onmessage = (event) => {
    pm.test("Echo response received", () => {
        pm.expect(event.data).to.eql("Hello");
    });
};

Mock-server și monitorizare în Postman

Mock-serverele Postman permit emularea endpointurilor API pe baza colecțiilor existente. Acest lucru este util când backendul nu este încă gata, iar frontendul sau aplicația mobilă este deja dezvoltată. Mock-serverul returnează un exemplu de răspuns din colecție cu anteturi corecte și cod de stare.

Crearea unui Mock-server

Mock-serverul se creează din colecție cu un singur clic: selectați colecția → Mock Servers → Add a new mock server. Postman generează un URL unic, care poate fi folosit în codul aplicației în locul API-ului real. Pentru fiecare cerere din colecție, mock-ul returnează Example Response salvat, ceea ce permite verificarea UI până la finalizarea backendului.

Monitorizarea API prin Postman Monitors

Monitors rulează colecția conform unui program (la fiecare 5 minute, oră sau zi) și verifică disponibilitatea și corectitudinea API. La eșecul unui test, monitorul trimite o notificare pe email sau în Slack. Monitorizarea funcționează din cloud-ul Postman, nu necesită server separat și suportă până la 10 000 de cereri pe lună la tariful gratuit.

// Test pentru monitorizare: verificarea timpului de răspuns
pm.test("Response time < 2000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
});

Securitate și gestionarea secretelor

Postman oferă mecanisme pentru lucrul sigur cu cheile API. Variabilele de tip Secret sunt criptate și nu sunt afișate în interfață. Pentru lucrul în echipă folosiți Workspace cu rolurile Admin, Editor și Viewer.

Criptarea variabilelor

La crearea unei variabile de mediu selectați tipul Secret — valoarea este ascunsă cu asteriscuri în toate interfețele. Secretele nu sunt exportate în colecție la partajare și nu sunt afișate în jurnalele Newman. Parolele și tokenurile sunt recomandate să fie stocate doar în variabilele Secret.

Integrarea cu Vault

Postman acceptă integrarea cu HashiCorp Vault și AWS Secrets Manager. Scripturile Pre-request pot solicita dinamic secrete din stocarea externă, excluzând păstrarea datelor sensibile în fișierele colecției și mediului.

Securitate și gestionarea secretelor

Postman oferă mecanisme pentru lucrul sigur cu cheile API. Variabilele de tip Secret sunt criptate și nu sunt afișate în interfață. Pentru lucrul în echipă folosiți Workspace cu rolurile Admin, Editor și Viewer.

Criptarea variabilelor

La crearea unei variabile de mediu selectați tipul Secret — valoarea este ascunsă cu asteriscuri în toate interfețele. Secretele nu sunt exportate în colecție la partajare și nu sunt afișate în jurnalele Newman. Parolele și tokenurile sunt recomandate să fie stocate doar în variabilele Secret.

Integrarea cu Vault

Postman acceptă integrarea cu HashiCorp Vault și AWS Secrets Manager. Scripturile Pre-request pot solicita dinamic secrete din stocarea externă, excluzând păstrarea datelor sensibile în fișierele colecției și mediului.