Postman: cos'è, test delle API e lavoro con le richieste

Cos'è Postman e le funzionalità principali

Postman è una piattaforma per lo sviluppo e il test delle API, disponibile come applicazione desktop (Windows, macOS, Linux) e versione web. Creato originariamente come estensione per Chrome nel 2012, Postman è diventato un ecosistema completo con supporto di monitoraggio, mock server e generazione di codice client.

Formati di richieste e risposte

Postman supporta tutti i metodi HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Il corpo della richiesta può essere nei formati JSON, XML, form-data, x-www-form-urlencoded e binary. La risposta viene visualizzata con evidenziazione della sintassi, Pretty-print e possibilità di vedere le intestazioni grezze.

Supporto dell'autenticazione

I tipi di autenticazione integrati includono Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, API Key e AWS Signature. Postman aggiunge automaticamente le intestazioni Authorization in base al tipo selezionato, accelerando il test degli endpoint protetti senza copiare manualmente i token.

Interfaccia di Postman e navigazione

L'interfaccia di Postman è composta da un pannello laterale (Collections, APIs, Environments), un'area di lavoro (Request Builder/Response Viewer) e un pannello inferiore (Console, Runner). La scheda Params consente di modificare i parametri di query dell'URL in vista tabellare, la scheda Headers gestisce le intestazioni HTTP.

Postman Console

Console (View → Show Postman Console) registra tutte le richieste e risposte di rete in ordine cronologico, incluse le reindirizzazioni intermedie e le intestazioni. È uno strumento indispensabile durante il debug di flussi OAuth complessi e catene di reindirizzamenti quando il Response Viewer standard mostra solo il risultato finale.

Workspaces e lavoro di squadra

Postman supporta spazi di lavoro di squadra con versionamento delle raccolte tramite Fork e Merge. I membri del team possono commentare le richieste, proporre modifiche e sincronizzare le raccolte in tempo reale. Public Workspace consente di pubblicare la documentazione API per sviluppatori esterni.

Creazione e invio di richieste HTTP

Una richiesta di base in Postman viene creata selezionando un metodo HTTP e inserendo un URL nella barra degli indirizzi. Dopo l'invio, la risposta viene visualizzata nel pannello inferiore con codice di stato, tempo di esecuzione e dimensione. I parametri della richiesta vengono codificati automaticamente durante l'inserimento.

Variabili dinamiche e snippet

Nell'URL e nel corpo della richiesta è possibile utilizzare variabili dinamiche nel formato {{$variable}}. Le variabili integrate {{$guid}}, {{$timestamp}} e {{$randomInt}} generano valori univoci per ogni richiesta. Gli snippet di codice sono disponibili tramite il pulsante Code (), che genera una richiesta equivalente in cURL, Python, JavaScript, Kotlin, Swift e altri linguaggi.

// Esempio di script in Pre-request: generazione della firma 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()
});

Raccolte e variabili d'ambiente

Le raccolte sono gruppi di richieste correlate combinate per progetto o modulo funzionale. Ogni raccolta può contenere cartelle annidate, intestazioni condivise e script Pre-request che vengono eseguiti prima di ogni richiesta nella raccolta. L'ordine delle richieste viene impostato tramite trascinamento.

Variabili d'ambiente e variabili globali

Postman supporta cinque livelli di variabili: global, collection, environment, data e local. La priorità di risoluzione dei conflitti va da locale a globale. I file di ambiente contengono coppie chiave-valore per diversi ambienti: development, staging, production. Il cambio di ambiente modifica automaticamente tutti gli URL e i token.

Automazione dei test delle API con script

Postman consente di scrivere test in JavaScript nella scheda Tests che vengono eseguiti dopo la ricezione della risposta. I test verificano il codice di stato, il corpo della risposta, le intestazioni e il tempo di esecuzione. I risultati vengono visualizzati nel pannello Test Results con indicatori di superamento colorati.

Libreria pm e concatenamento delle richieste

L'oggetto pm fornisce metodi per lavorare con la risposta: pm.response, pm.expect, pm.variables. Il concatenamento delle richieste viene implementato salvando i dati dalla risposta di una richiesta in una variabile e utilizzandoli nella successiva. Questa è la base per costruire test di integrazione e verificare la logica di business attraverso una sequenza di chiamate API.

// Test: verifica della struttura della risposta e salvataggio del token
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 e Newman

Collection Runner esegue tutte le richieste della raccolta in sequenza, eseguendo test a ogni passaggio. Newman è la versione console di Postman per pipeline CI/CD (Jenkins, GitHub Actions, GitLab CI). Newman esporta report nei formati JSON, JUnit e HTML per l'integrazione con sistemi di monitoraggio.

Lavoro con GraphQL e WebSocket

Le richieste GraphQL in Postman vengono inviate tramite POST a un singolo endpoint con corpo in formato JSON. La scheda GraphQL (Beta) fornisce un editor visivo con evidenziazione della sintassi, completamento automatico dei campi e schema. Le variabili della richiesta vengono passate in un pannello Variables separato.

Test di WebSocket e Socket.IO

Postman supporta le connessioni WebSocket tramite un'interfaccia separata con pannello dei messaggi. È possibile inviare messaggi di testo e binari, visualizzare la cronologia della connessione e riconnettersi automaticamente in caso di interruzione. Il client Socket.IO funziona in modalità di compatibilità con il protocollo Engine.IO.

// Test WebSocket in Postman tramite l'API pm
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 e monitoraggio in Postman

I mock server di Postman consentono di emulare endpoint API sulla base di raccolte esistenti. Questo è utile quando il backend non è ancora pronto, ma il frontend o l'app mobile è già in fase di sviluppo. Un mock server restituisce una risposta di esempio dalla raccolta con intestazioni e codice di stato corretti.

Creazione di un Mock server

Un mock server viene creato dalla raccolta con un clic: selezionare la raccolta → Mock Servers → Add a new mock server. Postman genera un URL univoco che può essere utilizzato nel codice dell'applicazione al posto della API reale. Per ogni richiesta della raccolta, il mock restituisce un'Example Response salvata, consentendo di testare l'interfaccia prima della fine del backend.

Monitoraggio delle API con Postman Monitors

Monitors eseguono una raccolta secondo una pianificazione (ogni 5 minuti, ora o giorno) e verificano disponibilità e correttezza dell'API. Quando un test fallisce, il monitor invia una notifica via email o su Slack. Il monitoraggio funziona dal cloud di Postman, non richiede un server separato e supporta fino a 10.000 richieste al mese nel piano gratuito.

// Test per il monitoraggio: verifica del tempo di risposta
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");
});

Sicurezza e gestione dei segreti

Postman fornisce meccanismi per lavorare in sicurezza con le chiavi API. Le variabili di tipo Secret vengono crittografate e non vengono visualizzate nell'interfaccia. Per il lavoro di squadra, utilizzare un Workspace con i ruoli Admin, Editor e Viewer.

Crittografia delle variabili

Quando si crea una variabile d'ambiente, selezionare il tipo Secret — il valore viene nascosto con asterischi in tutte le interfacce. I segreti non vengono esportati nella raccolta durante la condivisione e non vengono visualizzati nei log di Newman. Si consiglia di memorizzare password e token solo in variabili Secret.

Integrazione con Vault

Postman supporta l'integrazione con HashiCorp Vault e AWS Secrets Manager. Gli script Pre-request possono richiedere dinamicamente segreti da un archivio esterno, evitando di memorizzare dati sensibili nei file di ambiente della raccolta.

Sicurezza e gestione dei segreti

Postman fornisce meccanismi per lavorare in sicurezza con le chiavi API. Le variabili di tipo Secret vengono crittografate e non vengono visualizzate nell'interfaccia. Per il lavoro di squadra, utilizzare un Workspace con i ruoli Admin, Editor e Viewer.

Crittografia delle variabili

Quando si crea una variabile d'ambiente, selezionare il tipo Secret — il valore viene nascosto con asterischi in tutte le interfacce. I segreti non vengono esportati nella raccolta durante la condivisione e non vengono visualizzati nei log di Newman. Si consiglia di memorizzare password e token solo in variabili Secret.

Integrazione con Vault

Postman supporta l'integrazione con HashiCorp Vault e AWS Secrets Manager. Gli script Pre-request possono richiedere dinamicamente segreti da un archivio esterno, evitando di memorizzare dati sensibili nei file di ambiente della raccolta.