Guide pratiche

Documenta e verifica un'API dai suoi casi d'uso

Un'API utile consente a un altro team di capire cosa può richiedere e cosa riceverà. Il suo contratto dovrebbe essere verificabile, in versione e coerente con il servizio operativo.

vedere il metodo

Illustrazione — Documenta e verifica un'API dai suoi casi d'uso
Illustrazione generata dall’IA

Scegli le attività prima degli indirizzi

JavaScript: 9007199254740993 numerico viene arrotondato; la stringa mantiene cifre.
Illustrazione · Esempio JSON.parse: Number arrotonda, String conserva cifre. Concordare la rappresentazione prima della conversione.

Elenco utilizza come trovare un prodotto, leggere la disponibilità, aggiornare un record o tracciare l'elaborazione. Definire persone e sistemi autorizzati per ogni operazione. Un'API di lettura pubblica e un'API amministrativa hanno requisiti di accesso diversi.

Preparare un esempio di richiesta e risposta per ogni attività essenziale utilizzando valori sintetici e campi spiegati. distinguere identificatori stabili, etichette, unità e date. Definire i dati mancanti invece di sostituire i valori plausibili con informazioni sconosciute.

Definite gli identificatori grandi nel contratto JSON. Con Number binary64 di JavaScript, gli interi da −9007199254740991 a 9007199254740991 rientrano nell’intervallo esatto di interoperabilità RFC 8259. 9007199254740992 è rappresentabile ma non sicuro: il token vicino 9007199254740993 diventa 9007199254740992 nella decodifica JSON JavaScript standard.

Come stringa JSON, lo stesso identificatore conserva le cifre. Concordate il tipo fra produttore, schema e consumatore; convertire in testo un Number già arrotondato non recupera l’originale. Altre librerie possono mantenere più precisione: provate i client supportati. JSON valido non garantisce fedeltà e il tipo non deve cambiare silenziosamente.

Scorri la tabella orizzontalmente per leggere tutte le colonne. Con la tastiera, porta il focus sulla tabella e usa i tasti freccia.

Decodifica JSON JavaScript: precisione e tipo
Token JSON di esempioValore JavaScript mostratoInterpretazione
90071992547409919007199254740991Intero sicuro nell’esempio
90071992547409929007199254740992Esatto, ma fuori dall’intervallo sicuro
90071992547409939007199254740992Arrotondato: ultima cifra originale persa
"9007199254740993""9007199254740993"Stringa esatta; tipo testuale concordato

descrivere un contratto esplicito

OpenAPI fornisce un formato di descrizione indipendente dalla lingua per le API HTTP, che copre operazioni, parametri, risposte e modelli. Scegli una versione supportata dai tuoi strumenti e conserva il documento con il progetto; La versione più recente non è automaticamente la soluzione giusta per ogni toolchain.

Limiti di utilizzo del documento, impaginazione, filtri, ordinazioni, errori e risposte vuote. Non trattare i COR come prova di autorizzazione. Rivedere le operazioni e i controlli di accesso a livello di oggetto con il team tecnico.

Per un’API fittizia di gestione delle richieste, descrivete separatamente le quattro risposte seguenti. In questo contratto, 201 restituisce una risorsa creata con l’intestazione Location; 202 fornisce un riferimento di monitoraggio perché il lavoro non è concluso. Non trasformate ogni risposta 2xx in «operazione completata». Il client deve leggere stato, intestazioni e modello previsto per l’operazione.

Una risposta 204 non contiene un corpo da decodificare come JSON. Nell’esempio, un’istruzione sintatticamente corretta che viola una regola applicativa riceve 422 con un problema strutturato in application/problem+json. Se viene fornito il membro status, il generatore deve farlo coincidere con lo stato HTTP reale; il testo tradotto di detail non deve diventare la chiave decisionale del software. Documentate identificativi stabili del problema e la correzione attesa.

Scorri la tabella orizzontalmente per leggere tutte le colonne. Con la tastiera, porta il focus sulla tabella e usa i tasti freccia.

Quattro risposte di un’API fittizia e le conseguenze per il client
Risposta previstaFatto accertatoVerifica del consumatore
201 CreatedRisorsa creataVerificare Location previsto dal contratto e identificativo creato
202 AcceptedElaborazione accettata, non conclusaConservare il riferimento; attendere l’esito finale
204 No ContentAzione riuscita senza corpo di rispostaNon decodificare un corpo vuoto come JSON
422 Unprocessable ContentIstruzione compresa ma non elaborabile secondo la regolaLeggere il problema strutturato e proporre una correzione adeguata
  • RFC 9110 : HTTP Semantics

    RFC 9110, consultata il 22 ottobre 2026: semantica degli stati. Risposte e campi obbligatori definiscono un contratto fittizio.

  • RFC 9457 : Problem Details

    RFC 9457, consultata il 22 ottobre 2026: formato dei problemi e ruolo del membro status.

Evitare che una modifica sovrascriva quella di un altro redattore

  1. Due letture di r7
  2. Prima scrittura: r8
  3. Scrittura obsoleta: 412
  4. Confrontare prima di riprendere

Caso fittizio: due redattori aprono DEMO-17 con l’ETag forte "r7". Il primo salva una correzione e la rappresentazione attuale diventa "r8". Il secondo lavora ancora su "r7". Una scrittura condizionale può rilevare la differenza prima di sostituire la versione pubblicata.

In un’API che supporta questo contratto, il client invia If-Match con il validatore forte ricevuto. Il server confronta la versione prima di scrivere: l’esempio prevede 412 se è cambiata. W/"r7" è debole e non soddisfa il confronto forte. If-Match: * verifica l’esistenza di una rappresentazione attuale, non che sia rimasta invariata dopo la lettura.

Conservare la bozza del secondo redattore, leggere la versione attuale e mostrare le differenze prima di un nuovo invio. Sostituire automaticamente il validatore con "r8" e reinviare la vecchia bozza aggirerebbe la protezione. Controllo e scrittura devono essere indivisibili nell’archiviazione; due richieste concorrenti con lo stesso validatore non devono entrambe sovrascrivere la stessa versione.

Il controllo della concorrenza non sostituisce autenticazione, autorizzazioni sulla scheda o validazione dei campi. Non garantisce neppure l’esecuzione unica di una chiamata esterna. Verificare separatamente queste proprietà e documentare le precondizioni mancanti; 428 può richiedere una richiesta condizionale.

Scorri la tabella orizzontalmente per leggere tutte le colonne. Con la tastiera, porta il focus sulla tabella e usa i tasti freccia.

Due redattori, una versione attuale: sequenza di prova fittizia
FaseVersione e richiestaRisultato previsto dal contratto
Lettura di entrambiETag: "r7"Ognuno conserva il validatore con la bozza.
Primo salvataggioIf-Match: "r7" → versione "r8"La prima correzione viene conservata.
Secondo salvataggio obsoletoIf-Match: "r7"; versione attuale "r8"412; non sostituire la correzione salvata.
Confronto esplicitoLeggere "r8", confrontare e decidereConservare la bozza e verificare i permessi prima di riscrivere.

Test confini e autorizzazioni

Prova un oggetto esistente, un oggetto mancante, un parametro non valido e un elenco più lungo di una pagina. Controllare la pagina successiva per perdite o ripetizioni all'interno del modello di aggiornamento scelto. Limitazioni di stato che l'API non può garantire.

Usa gli account di prova con autorizzazioni diverse. Tentativo di letture e modifiche al di fuori dell'ambito consentito utilizzando dati sintetici. Registra gli stati attesi e i messaggi utili senza esporre tracce interne o segreti di configurazione.

Pianificare il cambiamento e il supporto

distinguere un campo aggiunto da un campo rimosso o un significato modificato. identificare i consumatori prima di un cambiamento incompatibile. Spiega il periodo di transizione e come rilevare le integrazioni ancora utilizzando il contratto precedente.

Fornire un esempio eseguibile per un ambiente di test, una matrice di test e un contatto tecnico. Metti in relazione gli errori osservati con esempi documentati dopo il rilascio. La documentazione limitata al caso ideale lascia gli integratori senza guida per i rifiuti e le interruzioni.

Documentazione primaria: Iniziativa OpenAPI - Specifiche.

Documenti di riferimento

Contenuto aggiornato

Riferimenti documentati per questo argomento

Riferimenti documentati per questo argomento
RiferimentoValore o sintassiAmbito
RFC 8259 · JSON
application/json · UTF-8JSON standard non ammette commenti né virgole finali; le stringhe usano virgolette doppie.
RFC 3339 · Date-time
2026-10-22T09:00:00+02:00Lo scarto esplicito collega l’ora locale a UTC; questo esempio non è un appuntamento.
HTTP · If-Match
If-Match: "r7" → 412If-Match confronta un validatore forte prima di scrivere. Nel contratto illustrato una versione superata riceve 412; conservare la bozza per confrontare le modifiche.
HTTP · 428
428 · Precondition Required428 permette al server di esigere una richiesta condizionale. L’uso va descritto nel contratto; lo stato non fornisce da solo un blocco.

Le date indicano la consultazione delle fonti. Questi riferimenti non costituiscono un audit del sito né una dichiarazione globale di conformità.

Distinguere stato HTTP, JSON e risultato operativo

Scelga uno scambio fittizio e provi a leggerlo localmente. Successo HTTP, JSON leggibile e operazione conclusa richiedono controlli distinti.

Gli estratti sono incompleti e usano indirizzi dimostrativi. La prova crea una Response in memoria: non contatta server né simula rete, cache o elaborazione operativa.

200Una nuova rappresentazione completa
Significato
Nel frammento il server risponde al GET condizionale con corpo JSON e validatore demo-v2.
Cosa verificare
Confronti If-None-Match, ETag e revisione del corpo. La prova locale analizza il JSON fornito nell’esempio.
Attenzione
Un 200 non garantisce JSON valido o dati operativi corretti. L’analisi riuscita non convalida lo schema dei propri dati.
Estratto di uno scambio fittizio
GET /demo/catalogue
If-None-Match: "demo-v1"

HTTP/1.1 200 OK
ETag: "demo-v2"
Content-Type: application/json

{"revision":"demo-v2"}

202Accettato, elaborazione ancora in attesa
Significato
202 indica accettazione per l’elaborazione, non completamento. Il corpo fittizio riporta queued.
Cosa verificare
Conservi DEMO-42 e segua lo stato secondo il contratto API, con permessi e limiti di ritentativo.
Attenzione
Response.ok vale true. Né questo valore né JSON leggibile provano il completamento. Campi e indirizzo di monitoraggio sono convenzioni fittizie.
Estratto di uno scambio fittizio
POST /demo/jobs

HTTP/1.1 202 Accepted
Location: /demo/jobs/DEMO-42
Content-Type: application/json

{"job":"DEMO-42","status":"queued"}

204Richiesta soddisfatta, nessun corpo
Significato
204 indica che il server ha soddisfatto la richiesta senza contenuto di risposta. Il frammento non trasmette JSON.
Cosa verificare
Gestisca il corpo assente secondo il contratto. Verifichi cosa conferma il destinatario prima di comunicare un risultato al visitatore.
Attenzione
Analizzare il corpo vuoto come JSON fallisce anche con Response.ok true. Per un webhook può essere confermata solo la ricezione; le azioni successive restano da verificare.
Estratto di uno scambio fittizio
POST /demo/events

HTTP/1.1 204 No Content

304Copia riconvalidata, nessun corpo nuovo
Significato
304 risponde a una richiesta condizionale: si può riutilizzare la rappresentazione conservata. Non fornisce un nuovo corpo.
Cosa verificare
Confronti il validatore inviato con la copia demo-v2 disponibile. L’interpretazione dipende anche dalla copia conservata.
Attenzione
La prova crea una Response 304 isolata, non una cache HTTP. Con un fetch reale il browser può fornire la risposta conservata: stato di rete e stato visto dallo script possono differire.
Estratto di uno scambio fittizio
GET /demo/catalogue
If-None-Match: "demo-v2"

HTTP/1.1 304 Not Modified
ETag: "demo-v2"

Riferimenti tecnici : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

Matrice di convalida funzionale per adattarsi al progetto

Questi controlli proposti utilizzano casi fittizi. Decidi quale comportamento è previsto con il team, annota il risultato e assegna discrepanze irrisolte prima della pubblicazione.

Scorri la tabella orizzontalmente per leggere tutte le colonne. Con la tastiera, porta il focus sulla tabella e usa i tasti freccia.

Casi di test, risultati attesi e prove utili
Casorisultato attesoProva da mantenere
Risorse presenti e assentiOgni risultato corrisponde allo stato documentato e al modello di risposta.richiesta, risposta e esempio di contratto corrispondente acquisito dall'ambiente di test.
Parametro fuori intervalloIl rifiuto è comprensibile e non espone traccia dello stack interno.messaggio pubblico e risultato mantenuto nella matrice di accettazione.
Due livelli di autorizzazioneUna risorsa proibita rimane inaccessibile anche con un identificatore noto.ha confrontato i risultati utilizzando due account sintetici con autorizzazioni esplicitamente diverse.
Impaginazione e filtro modificatoVengono definiti il comportamento di gestione dei token e riavvio del viaggio.Ordinamento, identificatori restituiti e regole che si applicano quando il filtro cambia.

Domande frequenti

La documentazione generata è sufficiente per testare un'API?

Aiuta a leggere un contratto, ma le autorizzazioni, i dati mancanti, gli errori, gli elenchi e le modifiche richiedono ancora test. Confronta gli esempi con le effettive risposte all'ambiente di prova.

COR sostituisce le autorizzazioni di accesso?

No. Le regole di origine incrociata non sostituiscono le operazioni del servizio e le autorizzazioni degli oggetti. Descrivi queste autorizzazioni e verifica l'applicazione sul lato server con gli account di test.