Risorse · 33
Far evolvere i contratti API senza perdere clienti.
Descrivere richieste, risposte ed errori; testare le versioni e rendere i webhook sicuri da riprodurre.
Aggiornato · 3 min
Obiettivi di questa guida
- Scrivere il contratto
- Chiarire gli errori
- Testare la compatibilità
- Pianificare la dismissione
Verifica rapida
- Quali client utilizzano ciascuna operazione?
- Gli errori hanno tipi stabili e stati coerenti?
- Un vecchio client può tollerare la modifica?
- I tentativi possono duplicare un'azione?
- Come verrà annunciata e verificata la dismissione?
Metodo passo passo
- 1
Inventariare i consumatori
Elencare operazioni, client, utilizzi, versioni e proprietari. Separare l'utilizzo osservato dalle ipotesi prima di modificare un campo.
Risultato: mappa delle dipendenze del contratto.
- 2
Descrivere richieste e risposte
Mantenere una descrizione OpenAPI con schemi, esempi realistici, risposte di successo e di errore. Verificarla rispetto al servizio in esecuzione.
Risultato: contratto versionato e test di conformità.
- 3
Stabilizzare gli errori
Utilizzare gli stati HTTP in base alla loro semantica e, ove utile, un tipo di problema documentato secondo RFC 9457. Non esporre segreti nei dettagli.
Risultato: catalogo degli errori testato.
- 4
Classificare la modifica
Ispezionare i campi obbligatori, i tipi, i valori, il comportamento, i timeout e la paginazione. Testare i vecchi client con la nuova versione utilizzando casi rappresentativi.
Risultato: matrice di compatibilità e decisione sulla versione.
- 5
Rendere le notifiche robuste
Per i webhook, pianificare l'autenticazione, la consegna non ordinata, i duplicati e i tentativi. Rendere l'elaborazione idempotente laddove la ripetizione sia possibile.
Risultato: scenario di replay e conferma.
- 6
Rilascio con percorso di uscita
Pubblicazione delle note di migrazione, del periodo di coesistenza e dei contatti. Monitoraggio dell'utilizzo della vecchia versione e dismissione solo dopo aver verificato gli utenti interessati.
Risultato atteso: piano di migrazione e documentazione relativa alla dismissione.
Indicatori di gestione
| Indicatore | Cosa misura | Prima azione |
|---|---|---|
| Contratto | Operazioni descritte e comportamento del servizio corrispondente | Correzione della divergenza |
| Compatibilità | Client rappresentativi testati prima della modifica | Aggiunta dei casi mancanti |
| Errori | Tipi documentati senza dati sensibili | Revisione di messaggi e schemi |
| Migrazione | Utilizzo della vecchia versione con un proprietario | Assistenza ai client rimanenti |
Errori comuni
- Presumere che il solo numero di versione preservi la compatibilità
- Documentazione di sole 200 risposte
- Restituzione di una traccia interna o di un segreto in caso di errore
- Presumere che i webhook arrivino una sola volta e in ordine
Domande frequenti
OpenAPI sostituisce i test?
No. Confrontare la descrizione con le risposte reali e le esigenze del consumatore.
Ogni modifica richiede una nuova versione?
No. Decidere in base all'impatto sul client e al comportamento contrattuale; Le modifiche incompatibili richiedono un piano esplicito.
Perché gli errori di battitura?
Offrono ai clienti un metodo affidabile per distinguere i problemi e scegliere un'azione.
Riferimenti ufficiali
I riferimenti supportano il metodo. Adattare i controlli al proprio contesto; non costituiscono una certificazione. I titoli dei riferimenti originali e i documenti di origine potrebbero essere in un'altra lingua.
