Tempo di lettura stimato : 8 min · Pubblicato
Scegli le attività prima degli indirizzi
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.
| Token JSON di esempio | Valore JavaScript mostrato | Interpretazione |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Intero sicuro nell’esempio |
| 9007199254740992 | 9007199254740992 | Esatto, ma fuori dall’intervallo sicuro |
| 9007199254740993 | 9007199254740992 | Arrotondato: 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.
| Risposta prevista | Fatto accertato | Verifica del consumatore |
|---|---|---|
| 201 Created | Risorsa creata | Verificare Location previsto dal contratto e identificativo creato |
| 202 Accepted | Elaborazione accettata, non conclusa | Conservare il riferimento; attendere l’esito finale |
| 204 No Content | Azione riuscita senza corpo di risposta | Non decodificare un corpo vuoto come JSON |
| 422 Unprocessable Content | Istruzione compresa ma non elaborabile secondo la regola | Leggere 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
- Due letture di r7
- Prima scrittura: r8
- Scrittura obsoleta: 412
- 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.
| Fase | Versione e richiesta | Risultato previsto dal contratto |
|---|---|---|
| Lettura di entrambi | ETag: "r7" | Ognuno conserva il validatore con la bozza. |
| Primo salvataggio | If-Match: "r7" → versione "r8" | La prima correzione viene conservata. |
| Secondo salvataggio obsoleto | If-Match: "r7"; versione attuale "r8" | 412; non sostituire la correzione salvata. |
| Confronto esplicito | Leggere "r8", confrontare e decidere | Conservare la bozza e verificare i permessi prima di riscrivere. |
- IETF · RFC 9110 § 13.1.1
IETF : Scritture condizionali e precondizioni
- IETF · RFC 6585 § 3
428 · Precondition Required
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
- Iniziativa OpenAPI - Specifiche · Fonte consultata
- IETF : RFC 8259: JSON numbers · Fonte consultata
- TC39 : Number.isSafeInteger · Fonte consultata
Contenuto aggiornato
Riferimenti documentati per questo argomento
| Riferimento | Valore o sintassi | Ambito |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON standard non ammette commenti né virgole finali; le stringhe usano virgolette doppie. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Lo scarto esplicito collega l’ora locale a UTC; questo esempio non è un appuntamento. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-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 Required | 428 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à.
