Valutare dal punto di vista del client
La tabella orienta la revisione, senza garanzie universali. Campi aggiunti possono disturbare lettori rigidi; nuovi valori enumerati possono rompere gestioni esaustive. Censire client, librerie e ipotesi.
| Modifica | Rischio | Prova richiesta |
|---|---|---|
| Eliminare o rinominare un campo | Lettura impossibile | Migrazione esplicita e test client. |
| Aggiungere campo facoltativo | Lettore rigido o conflitto di nome | Test dei consumatori esistenti. |
| Nuovo valore nella risposta | Gestione esaustiva incompleta | Comportamento per valori sconosciuti. |
| Cambiare valore predefinito | Esito funzionale diverso | Confrontare casi senza valore esplicito. |
Organizzare la coesistenza
- Descrivere vecchie e nuove strutture, valori predefiniti, errori, paginazione e permessi. Eseguire test di contratto su casi rappresentativi.
- Scegliere esplicitamente come selezionare la versione. Distinguere versione del servizio e del documento OpenAPI; verificare cache e gateway.
- Pubblicare calendario, guida e contatto. Rilevare l’uso effettivo con telemetria proporzionata e preparare un ripristino compatibile con i dati.
Distinguere deprecazione e arresto
Deprecation segnala risorse deprecate; Sunset può annunciarne la prevista indisponibilità. Gli header non migrano i client. Prima del ritiro, esaminare consumatori rimasti, obblighi e procedura di recupero.
Fonti primarie
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Impatto della versione sul consumatore
L'aggiunta di un numero a un URL non garantisce la conservazione dei client esistenti. Un tipo, un valore previsto, un comportamento o una risposta di errore modificati possono risultare incompatibili anche se il percorso rimane invariato.
- Inventario dei client attivi e utilizzo osservato.
- Testare le versioni precedenti dei client con il nuovo contratto.
- Pubblicare un periodo di coesistenza e verificarne l'utilizzo prima della dismissione.
Fonte primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Metodo correlato: consultare la guida pratica.
Attività API asincrone
Accettare una richiesta non dimostra che il lavoro sia concluso.
- Account, operazione e identificativo riutilizzabile
- Stato, ora, intervallo e scadenza
- Risultato, errore, annullamento ed effetti residui
- Una sola attività autorizzata ed esito verificato dopo interruzione
Caso di accettazione riproducibile
Esempio fittizio: questi dati non descrivono clienti o risultati osservati.
Vedi dati del caso
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Decisione attesa
Un 200 nella lettura dello stato non significa elaborazione conclusa. Dopo una richiesta di annullamento, conta solo l’esito confermato.
Annullamento richiesto troppo tardi
Scenario immaginario: stessa attività J-42, secondi dall’invio. Gli stati appartengono al contratto dell’esempio; HTTP non li impone.
| Istante | Risposta e stato | Conclusione giustificata |
|---|---|---|
| +0 s | HTTP 202 · pending | Accettata per elaborazione; nessun risultato finale confermato. |
| +5 s | HTTP 200 · running | La lettura dello stato è riuscita; l’attività continua. |
| +6 s | HTTP 200 · cancel_requested | Richiesta di arresto registrata; annullamento da confermare. |
| +7 s | HTTP 200 · succeeded | L’elaborazione ha vinto la corsa. Mostrare il successo osservato e verificare gli effetti; non dichiarare annullamento. |
202 dimostra che il lavoro terminerà?
No. Conferma l’accettazione per elaborazione, non l’esito finale. Consulta lo stato dell’operazione.
Fonte primaria: MDN — 202 Accepted. Metodo correlato: consultare la guida pratica.
Aggiornamenti software: verificare un cambio di firmatario
Decidere se un artefatto firmato corrisponde ancora a produttore, processo e versione approvati.
- Prima di esaminare il pacchetto, registra produttore, chiave o identità del certificato, emittente e processo di build autorizzati. Collega le attese al software e a un canale già affidabile. L’artefatto non deve definire da solo la propria politica di accettazione.
- Confronta l’impronta del file ricevuto con l’oggetto dell’attestazione. Verifica la firma con le radici di fiducia previste, poi identità, builder e parametri. Una firma valida di un’altra identità non soddisfa la politica del servizio.
- Prova rotazione annunciata, emittente inatteso, firma assente e file diverso. Mantieni in attesa l’artefatto se la nuova identità non è confermata. Registra approvazione e ritorno; una firma non prova assenza di vulnerabilità.
Caso di accettazione riproducibile
Esempio fittizio: questi dati non descrivono clienti o risultati osservati.
Vedi dati del caso
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Decisione attesa
Esempio fittizio: impronta e firma sono valide, ma il firmatario differisce da quello approvato. L’installazione resta in attesa di conferma indipendente del cambio.
Fonte primaria: SLSA v1.2 — Verifying artifacts. Metodo correlato: consultare la guida pratica.
API: deprecazione e ritiro
Le note dettagliate di questa edizione sono disponibili in inglese.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23