Come verificare le informazioni sulla definizione dell’API?

Cosa significa definizione dell’API nella pratica

Per definizione dell’API si intende in genere la specifica formale del funzionamento di un’API: gli endpoint disponibili (o operazioni), gli input richiesti, gli input opzionali, gli output previsti, i tipi di dati, le regole di convalida e i formati degli errori. Può essere espressa tramite un documento OpenAPI/Swagger, uno schema JSON, una specifica interna per sviluppatori o documentazione leggibile da esseri umani.

Quando si verificano informazioni su una definizione dell’API, non si cerca di confermare se un’idea sia “vera” in senso generale, ma si controlla se il contratto documentato sia coerente, testabile e riproducibile per una determinata versione dell’API.

Come funziona il processo di verifica (gerarchia delle fonti)

Utilizza una gerarchia di fonti che corrisponda al modo in cui vanno confermate le “meccaniche stabili”.

1. Articoli contrattuali primari (più stabili)

   • I documenti effettivi della definizione dell’API pubblicati dal fornitore (ad esempio, il file OpenAPI).
   • Eventuali schemi leggibili da macchina inclusi nella documentazione.
   • L’identificatore di versione documentato e il registro delle modifiche.

2. Documentazione del fornitore (livello interpretativo)

   • Guide che descrivono come formulare richieste e interpretare le risposte.
   • Sezioni su gestione degli errori e autenticazione/autorizzazione, se influenzano la struttura di richieste e risposte.

3. Comportamento osservato da un test controllato (verifica pratica)

   • Un piccolo insieme di richieste in un ambiente non produttivo o sandbox, se disponibile.
   • Convalida che campi, tipi e vincoli delle risposte corrispondano alla definizione.

In pratica, la verifica è più solida quando si riesce a dimostrare che documentazione, schema e risposte sono coerenti per la stessa versione.

Evidenze e passaggi riproducibili per la verifica

Segui un processo passo dopo passo che puoi ripetere.

Passo 1: Fissa la versione e l’ambito

Annota la versione dell’API e l’artefatto esatto della definizione che stai utilizzando (nome file, URL o identificatore di commit). Presupponi che versioni diverse possano avere nomi di campo, parametri richiesti e formati di errore differenti.

Passo 2: Confronta la struttura con la definizione

Per ogni endpoint di interesse, verifica che:

• L’elenco dei parametri richiesti sia esplicito.
• I parametri opzionali siano distinguibili.
• I campi di output siano documentati con tipi di dati o schemi.
• Le risposte di errore abbiano una struttura documentata (ad esempio, un codice di errore più un messaggio, o un elenco di problemi di convalida).

Passo 3: Crea casi di test minimi con assunzioni esplicite

Scegli un piccolo insieme di richieste che coprano:

• Un caso “percorso felice” con soli campi obbligatori.
• Un caso di convalida (tipo errato o campo obbligatorio mancante) per confermare il comportamento in caso di errore.

Presupponi l’assenza di dati di mercato in tempo reale. Se l’API richiede parametri solitamente dipendenti da uno stato esterno (come simboli o identificatori), utilizza valori forniti dal tuo ambiente di test, oppure considera valori mancanti o non validi come input di test anziché cercare di prevedere gli esiti.

Passo 4: Confronta le risposte con la definizione

Per ogni risposta:

• Verifica che il payload della risposta includa i campi descritti.
• Controlla che i tipi di dati corrispondano alle aspettative (stringa vs numero, oggetto vs lista).
• Conferma che gli errori abbiano la struttura documentata quando le richieste non sono valide.

Se la definizione afferma che un campo è opzionale ma questo non appare mai nelle risposte, si tratta di una discrepanza da registrare. Al contrario, se compaiono regolarmente campi aggiuntivi, registrati come “osservati ma non documentati”, il che potrebbe indicare una lacuna nella documentazione.

Passo 5: Monitora i modi di errore, non solo gli esiti

Almeno una limitazione significativa dovrebbe far parte della verifica:

• Deriva di versione: la documentazione può restare indietro rispetto al comportamento dopo aggiornamenti.
• Schemi incoerenti: i campi possono essere documentati ma mancanti o rinominati.
• Differenze nella convalida: i formati degli errori possono cambiare tra endpoint.
• Differenze tra ambienti: il comportamento in sandbox e produzione potrebbe non corrispondere.

Tratta questi casi come risultati della verifica, non come segnali di correttezza.

Limitazioni e rischi da aspettarsi

Anche con controlli accurati, la verifica è limitata dall’incertezza e dai cambiamenti.

• Nessun singolo test garantisce accuratezza a lungo termine. Una definizione può essere corretta oggi ma diventare obsoleta dopo aggiornamenti del fornitore.
• Il comportamento può variare in base al contesto. Costi, condizioni di esecuzione, permessi e guasti di rete possono cambiare le risposte osservate, anche quando il contratto è stabile.
• L’accordo storico non garantisce accordo futuro. Se in passato le risposte corrispondevano, ciò non garantisce che lo faranno dopo un cambio di versione.

A causa di questi limiti, mantieni la verifica legata a una versione specifica e a un ambiente di test specifico.

Checklist di verifica e prossima domanda da risolvere

Usa questa checklist per rendere la tua verifica riproducibile:

• Versione registrata sia per la documentazione che per i test.
• Endpoint e campi elencati a partire dalla definizione.
• Richieste minime “percorso felice” e “errore di convalida” create con assunzioni esplicite.