Come si usa Postman?

Postman è uno strumento potente e versatile per testare, documentare e automatizzare le API. Originariamente sviluppato come estensione per Chrome, oggi è una piattaforma completa che permette agli sviluppatori di interagire con i servizi web in modo efficiente.

Le API (Application Programming Interfaces) sono fondamentali nello sviluppo moderno, poiché consentono ai sistemi di comunicare tra loro. Tuttavia, senza strumenti adeguati, il debug e il testing possono essere complessi. Postman semplifica questo processo grazie a funzionalità come:

• Invio di richieste HTTP senza dover scrivere codice.
• Visualizzazione strutturata delle risposte, utile per individuare errori.
• Gestione di API tramite collezioni di richieste, che ne facilitano l’organizzazione.
• Automazione dei test con script in JavaScript.
• Collaborazione in team, con la condivisione di richieste e documentazione.

Postman è utile sia per chi sviluppa API sia per chi le utilizza, accelerando il processo di sviluppo e testing.

Installazione e configurazione iniziale

Postman è disponibile per i principali sistemi operativi (Windows, macOS, Linux). Per installarlo:

1. Scarica l’applicazione dal sito ufficiale: https://www.postman.com/downloads/
2. Segui la procedura di installazione per il tuo sistema operativo.
3. Avvia l’app e, se desideri, crea un account per sincronizzare le richieste tra più dispositivi.

Se non vuoi installarlo puoi sempre usare la versione web based.

Panoramica dell'interfaccia di Postman

Una volta avviato, Postman presenta diverse sezioni fondamentali:

• Workspace: area di lavoro per organizzare e gestire le richieste API.
• Request Builder: spazio per configurare le richieste HTTP scegliendo metodo, URL, parametri, intestazioni e corpo della richiesta.
• Response Viewer: sezione in cui vengono visualizzate le risposte del server (JSON, XML, HTML, testo).
• Collezioni: insieme organizzato di richieste API, utile per testing ripetitivo e documentazione.
• Environments: gestione di variabili globali o locali per testare API in diversi contesti (es. sviluppo, staging, produzione).
• Flows: interfaccia visuale per creare flussi automatizzati di test e interazioni tra API, senza necessità di scrivere codice.
• APIs: sezione dedicata alla gestione centralizzata delle API, che permette di definire e documentare endpoint, versioni e specifiche (supporta OpenAPI, RAML, GraphQL).
• Mock Server: funzionalità che consente di simulare risposte API senza un backend attivo, utile per testare applicazioni client prima dello sviluppo dell’API reale.
• Monitors: strumenti di automazione per eseguire richieste API a intervalli regolari, monitorando lo stato delle API e ricevendo notifiche in caso di errori o tempi di risposta elevati.

Creare e testare un'API con Postman

Per comprendere meglio Postman, creiamo un server API con Node.js ed Express:

1import express from 'express';
2import bodyParser from 'body-parser';
3import jwt from 'jsonwebtoken';
4
5const app = express();
6const PORT = 3000;
7const SECRET_KEY = "supersegreto";
8
9app.use(bodyParser.json());
10
11let posts = [
12    { id: 1, title: 'Primo post', content: 'Contenuto del primo post' },
13    { id: 2, title: 'Secondo post', content: 'Contenuto del secondo post' }
14];
15
16const users = [{ username: 'admin', password: 'password' }];
17
18app.post('/login', (req, res) => {
19    const { username, password } = req.body;
20    const user = users.find(u => u.username === username && u.password === password);
21
22    if (user) {
23        const token = jwt.sign({ username }, SECRET_KEY, { expiresIn: '1h' });
24        return res.json({ token });
25    }
26
27    res.status(401).json({ error: 'Credenziali non valide' });
28});
29
30const authenticate = (req, res, next) => {
31
32    const token = req.headers['authorization'];
33
34    if (!token) return res.status(403).json({ error: 'Token richiesto' });
35    try {
36        req.user = jwt.verify(token.split(" ")[1], SECRET_KEY);
37        next();
38    } catch {
39        res.status(401).json({ error: 'Token non valido' });
40    }
41
42};
43
44app.get('/posts', authenticate, (req, res) => {
45    res.json(posts);
46});
47
48app.post('/posts', authenticate, (req, res) => {
49    const newPost = { id: posts.length + 1, ...req.body };
50    posts.push(newPost);
51    res.status(201).json(newPost);
52});
53
54app.listen(PORT, () => console.log(`Server in ascolto su porta ${PORT}`));

Avvia il server con:

1node server.js

Ora possiamo testare le API con Postman.

Effettuare richieste con Postman

1. In Postman, crea una nuova richiesta POST verso http://localhost:3000/login.
2. Nella scheda Body, seleziona raw e il formato JSON.
3. Inserisci questo payload: {"username": "admin", "password": "password"}
4. Clicca su Send per ricevere un token JWT nella risposta.

Salvare il token JWT in Postman

Nella scheda Scripts, aggiungi questo script nella sezione post-response:

1pm.test("Token JWT ricevuto e memorizzato", function () {
2    pm.response.to.have.status(200);
3    const jsonData = pm.response.json();
4    pm.environment.set("jwt_token", jsonData.token);
5});

Clicca su Send per memorizzare il token JWT. Assicurarsi di aver selezionato un ambiente per fare in modo che il token venga memorizzato correttamente.

Richiesta GET autenticata

1. Crea una nuova richiesta GET verso http://localhost:3000/posts.
2. Nella sezione Authorization, aggiungi un’autenticazione di tipo Bearer Token con valore {{jwt_token}}.
3. Clicca su Send per ricevere l’elenco dei post.

Automazione dei Test con Postman

Postman permette di scrivere script di test per automatizzare la verifica delle API.

Test per la richiesta GET

1pm.test("Verifica status code 200", function () {
2    pm.response.to.have.status(200);
3});
4
5pm.test("Verifica che ci sia almeno un post", function () {
6    const jsonData = pm.response.json();
7    pm.expect(jsonData.length).to.be.at.least(1);
8});

Test per la richiesta POST

1pm.test("Verifica status code 201", function () {
2    pm.response.to.have.status(201);
3});
4
5pm.test("Verifica che il post sia stato creato", function () {
6    const jsonData = pm.response.json();
7    pm.expect(jsonData.title).to.equal("Nuovo post da Postman");
8});

Testing Avanzato

Quando si lavora con le API, è importante assicurarsi che la struttura dei dati restituiti sia sempre conforme allo schema previsto. Per farlo, Postman permette di eseguire la validazione dello schema JSON utilizzando la libreria Ajv (Another JSON Schema Validator), che è attualmente uno dei migliori strumenti per questa operazione.

Di seguito, un esempio di validazione della risposta JSON di un endpoint che restituisce un post:

1const Ajv = require('ajv');
2const ajv = new Ajv({ allErrors: true, strict: false }); // Abilita la validazione di tutti gli errori
3
4const schema = {
5    type: "object",
6    properties: {
7        id: { type: "integer", minimum: 1 }, // ID deve essere un intero positivo
8        title: { type: "string", minLength: 3, maxLength: 100 }, // Il titolo deve avere tra 3 e 100 caratteri
9        content: { type: "string", minLength: 10 } // Il contenuto deve avere almeno 10 caratteri
10    },
11    required: ["id", "title", "content"], // Campi obbligatori
12    additionalProperties: false // Non permette campi extra
13};
14
15pm.test("Schema della risposta valido", function () {
16    const jsonData = pm.response.json();
17   const validate = ajv.compile(schema);
18    const valid = validate(jsonData);
19
20    if (!valid) {
21        console.error("Errori di validazione:", validate.errors);
22    }
23
24    pm.expect(valid, "La risposta non rispetta lo schema previsto").to.be.true;
25});
26
27Cosa fa questo test?
28
29* Ajv viene inizializzato con `allErrors: true` per mostrare tutti gli errori invece di fermarsi al primo errore rilevato.
30* Lo schema JSON definisce la struttura prevista per un post:
31    * L’`id` deve essere un intero positivo (`minimum: 1`).
32    * Il `title` deve avere tra 3 e 100 caratteri.
33    * Il `content` deve avere almeno 10 caratteri.
34    * Non sono ammessi campi extra (`additionalProperties: false`).
35* Se la validazione fallisce, gli errori vengono stampati in console, permettendo di identificare il problema.
36
37### Verifica del codice di stato
38
39Oltre alla validazione della struttura, è fondamentale verificare che l'API restituisca il codice di stato corretto per ogni richiesta effettuata. Ad esempio, quando un nuovo post viene creato correttamente, l'API dovrebbe restituire un `201 Created`.
40
41Il test seguente controlla che il codice di stato della risposta sia corretto:

}); ```

Verifica dei dati restituiti

Dopo aver verificato la struttura e il codice di stato, è utile controllare che i dati restituiti dall’API siano effettivamente quelli attesi.

1pm.test("Verifica che il post sia stato creato correttamente", function () {
2    const jsonData = pm.response.json();
3    pm.expect(jsonData).to.be.an("object"); // Verifica che la risposta sia un oggetto JSON
4    pm.expect(jsonData).to.have.property("title"); // Controlla che il campo "title" esista
5    pm.expect(jsonData).to.have.property("content"); // Controlla che il campo "content" esista
6    pm.expect(jsonData.title).to.equal("Nuovo post da Postman"); // Controlla il valore del titolo
7    pm.expect(jsonData.content).to.be.a("string"); // Verifica che il contenuto sia una stringa
8});

Cosa fa questo test?

• Controlla che la risposta sia un oggetto JSON valido.
• Verifica che i campi title e content siano presenti.
• Confronta il titolo ricevuto con il valore atteso.
• Si assicura che content sia una stringa.

Test delle performance

Un altro aspetto importante nella validazione di un’API è il tempo di risposta. Se un endpoint impiega troppo tempo per restituire i dati, può essere un segnale di problemi di performance.

Postman permette di impostare test automatici per verificare che la risposta venga ricevuta entro un tempo massimo prestabilito. Nell’esempio seguente, il test verifica che il server risponda in meno di 200 millisecondi:

1pm.test("Tempo di risposta inferiore a 200ms", function () {
2    pm.expect(pm.response.responseTime, "La risposta è stata troppo lenta").to.be.below(200);
3});

Se l’API impiega più di 200ms per rispondere, il test fallirà e verrà mostrato un messaggio di errore. Se vuoi visualizzare il tempo di risposta lo trovi sopra al response viewer a destra affianco al codice di stato.

Visualizzazione avanzata dei dati con Postman Visualizer

Postman consente di personalizzare la visualizzazione dei dati di risposta utilizzando HTML, CSS e JavaScript. Questa funzionalità è utile per rappresentare i dati API in tabelle, grafici o layout personalizzati.

Utilizziamo Postman Visualizer per creare una tabella interattiva che mostra i dati restituiti dall'API.

Esempio di template HTML:

1const template = `
2<style>
3    table {
4        width: 100%;
5        border-collapse: collapse;
6        background-color: #fff;
7    }
8
9    th, td {
10        border: 1px solid #fff;
11        padding: 8px;
12        text-align: left;
13    }
14
15    th {
16        background-color: #aaa;
17    }
18
19    tr:nth-child(even) {
20        background-color: #ccc;
21    }
22</style>
23
24<table>
25    <thead>
26        <tr>
27            <th>ID</th>
28            <th>Title</th>
29            <th>Content</th>
30        </tr>
31    </thead>
32    <tbody>
33        {{#each json}}
34        <tr>
35            <td>{{id}}</td>
36            <td>{{title}}</td>
37            <td>{{content}}</td>
38        </tr>
39        {{/each}}
40    </tbody>
41</table>
42`;
43
44// Passiamo i dati JSON ricevuti dalla risposta API
45let responseData = {
46    json: pm.response.json() // Carichiamo la risposta API nel template
47};
48
49// Impostiamo il visualizzatore con il template HTML e i dati JSON
50pm.visualizer.set(template, responseData);

• Il template HTML crea una tabella con intestazioni per ID, Titolo e Contenuto.
• La sintassi {{#each json}} ... {{/each}} scorre i dati JSON ricevuti e li popola dinamicamente nella tabella.
• Il codice CSS migliora la leggibilità della tabella, aggiungendo sfondi alternati per le righe e bordi più chiari.
• L'oggetto responseData memorizza i dati della risposta API per renderli disponibili al template.

Personalizzazioni Avanzate

Se vogliamo visualizzare i dati API come grafico a barre, possiamo integrare Chart.js nel template:

1var template = `
2<h2 style="color: #fff; font-family: sans-serif;">Lunghezza dei post</h2>
3<canvas id="myChart" height="150"></canvas>
4<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.4/Chart.min.js"></script>
5<script>
6document.addEventListener("DOMContentLoaded", function () {
7    var ctx = document.getElementById("myChart").getContext("2d");
8    // Creazione del grafico con dati inizialmente vuoti
9    var myChart = new Chart(ctx, {
10        type: "bar",
11        data: {
12            labels: [],
13            datasets: [{
14                label: "Lunghezza contenuto",
15                data: [],
16                backgroundColor: "rgba(75, 192, 192, 0.2)",
17                borderColor: "rgba(75, 192, 192, 1)",
18                borderWidth: 1
19            }]
20        },
21        options: {
22            responsive: true,
23            maintainAspectRatio: false,
24            scales: {
25                yAxes: [{
26                    ticks: {
27                        beginAtZero: true
28                    }
29                }]
30            }
31        }
32    });
33
34    // Recupero dei dati JSON passati dal test script
35    pm.getData(function (err, value) {
36        if (!err) {
37            myChart.data.labels = value.titles;
38            myChart.data.datasets[0].data = value.content_lengths;
39            myChart.update();
40        }
41    });
42});
43</script>
44`;
45
46// Estrazione e formattazione dei dati dalla risposta JSON
47let jsonData = pm.response.json();
48
49// Controllo dei dati ricevuti
50if (!Array.isArray(jsonData) || jsonData.length === 0) {
51    jsonData = [{ title: "Nessun dato", content: "" }];
52}
53
54let chartData = {
55    titles: jsonData.map(post => post.title), // Array dei titoli dei post
56    content_lengths: jsonData.map(post => post.content.length) // Array della lunghezza dei contenuti
57};
58
59// Passiamo il template e i dati al visualizzatore
60pm.visualizer.set(template, chartData);

Documentazione API con Postman

Oltre a testare e visualizzare le API, Postman fornisce strumenti per documentarle in modo automatico. Una documentazione chiara e dettagliata è fondamentale per garantire che altri sviluppatori possano comprendere e utilizzare l’API senza difficoltà.

Creazione della Documentazione

Per ogni richiesta API all'interno di una collezione, Postman permette di aggiungere descrizioni dettagliate. Le informazioni fondamentali da includere sono:

• Scopo della richiesta: Spiega il motivo dell'endpoint e cosa restituisce.
• Parametri richiesti: Elenca i parametri di:
  • Query (es. ?id=1).
  • Body (es. JSON da inviare in una richiesta POST).
  • Headers (es. Authorization: Bearer <token>).
• Esempi di richiesta e risposta: Aiutano a comprendere il formato dei dati attesi.

Aggiunta di esempi

Postman consente di salvare esempi di richieste e risposte direttamente nella collezione. Questi esempi facilitano la comprensione dell’API per gli sviluppatori che la utilizzano.

Pubblicazione della Documentazione

Postman offre diverse opzioni per condividere la documentazione generata:

• Condivisione tramite Postman:
  1. Seleziona una collezione e clicca su "Publish".
  2. Postman genererà automaticamente una documentazione interattiva, accessibile via URL pubblico o privato.
  3. La documentazione include dettagli sugli endpoint, parametri e risposte attese.
• Integrazione con strumenti di API Management: Postman permette anche di collegare le API a strumenti di gestione avanzata come:
• AWS API Gateway
• Azure API Management
• Kong API Gateway

Queste integrazioni facilitano il monitoraggio, la gestione e la sicurezza delle API in ambienti di produzione.

Best Practices per una Documentazione Efficace

Per garantire che la documentazione sia utile e aggiornata, è importante seguire alcune buone pratiche:

• Usa descrizioni dettagliate: Ogni endpoint deve avere una spiegazione chiara del suo funzionamento.
• Includi esempi di richieste e risposte: Gli esempi aiutano a comprendere il formato dei dati attesi.
• Mantieni la documentazione aggiornata: Ogni modifica all’API deve riflettersi nella documentazione.
• Utilizza variabili ed environment: Per semplificare i test e le richieste dinamiche.

In questa lezione abbiamo esplorato le principali funzionalità di Postman, uno strumento indispensabile per chiunque lavori con le API. Abbiamo visto come Postman semplifica il testing, la documentazione e l'automazione delle API, offrendo un'interfaccia intuitiva e una vasta gamma di funzionalità avanzate.

Dall'invio di semplici richieste HTTP alla creazione di test automatizzati, dalla validazione dello schema JSON alla visualizzazione personalizzata dei dati, Postman si rivela uno strumento completo e versatile, adatto a sviluppatori di ogni livello.

Che tu sia un principiante alle prime armi con le API o un professionista esperto, Postman ti aiuterà a migliorare la qualità del tuo lavoro, rendendo più efficiente e produttivo il processo di sviluppo e testing delle API.