Valida il JSON prima delle richieste API

Perché validare prima di inviare

Quando una richiesta API fallisce, il messaggio può puntare ad autenticazione, permessi, validazione di schema o JSON malformato. Validare il body JSON prima elimina un’intera classe di fallimenti prima che la richiesta raggiunga il server. Inoltre rende più facili da rivedere comandi cURL copiati, body Postman, sample di webhook e test di integrazione.

Controlli di sintassi da eseguire

Una passata di validazione JSON strict dovrebbe confermare che il body parsi come JSON e che l’output formattato corrisponda a quello che intendi inviare.

• Ogni stringa e ogni chiave di oggetto usa virgolette doppie
• Niente commenti né virgole finali
• I booleani sono true o false, non True o False
• I valori assenti sono null o chiavi omesse, non undefined
• Il valore di livello superiore corrisponde a quanto si aspetta l’endpoint

Anche gli header contano

Un body JSON valido può comunque fallire se la richiesta non dichiara il Content-Type corretto. Per la maggior parte delle API JSON invia Content-Type: application/json. Se l’endpoint controlla anche Accept, aggiungi Accept: application/json per far concordare client e server sul formato.

Body di richiesta errato

{ userId: 42, active: True, tags: ['beta',], }

Body di richiesta corretto

{ "userId": 42, "active": true, "tags": ["beta"] }

Dopo la validazione sintattica

La validazione sintattica dimostra solo che il documento è parsabile. Per richieste di produzione controlla anche lo schema: campi obbligatori, campi sconosciuti, tipi dei valori, lunghezze degli array, valori enum, stringhe di data e se gli identificatori numerici devono essere numeri o stringhe.

Suggerimento di debug

Se il server continua a rifiutare un JSON valido, confronta il body formattato con un esempio noto. Un diff JSON semantico trova le vere differenze di valori ignorando l’ordine delle chiavi, particolarmente utile quando i payload sono generati da strumenti diversi.

Un piccolo wrapper fetch + Ajv

Valida il corpo della risposta contro uno schema noto prima di consegnarlo al codice applicativo. Compila lo schema una sola volta al caricamento del modulo e proteggi ogni chiamata: const validate = ajv.compile(schema); const res = await fetch(url); const data = await res.json(); if (!validate(data)) throw new Error("Schema mismatch: " + ajv.errorsText(validate.errors)); return data; — così le rotture di contratto a monte emergono al confine, non cinque livelli più in basso.