Chiarire il compito e la decisione
Questa guida trasforma API QuickStart in un flusso di lavoro operativo rivedibile. Collega le decisioni di dominio, la proprietà, le prove e l'accettazione in modo che il risultato continui a funzionare in produzione.
Inizia con una richiesta autenticata, convalida il contratto di risposta e aggiungi la gestione degli errori prima di connettere CMS.
Procedura pratica
- 1
Tipi di origini dell'inventario, identificatori, campi, impostazioni locali, proprietari e stati di pubblicazione.
- 2
Scegli il modello di distribuzione tra volume, latenza, controllo editoriale e tolleranza agli errori.
- 3
Mappare il record di origine su un record di versione in lingua separato con collegamento durevole.
- 4
Aggiungi autenticazione, idempotenza, nuovi tentativi, invalidazione della cache, registrazione e controlli di accesso.
- 5
Testare la pubblicazione, le modifiche all'origine, i risultati non disponibili, il rollback, il funzionamento della tastiera e il monitoraggio prima del rilascio.
Esempio o strumento
Una coppia completa di richiesta e risposta include autenticazione, impostazioni locali, modalità, idempotenza e gestione degli errori. Nello strumento, registra anche la baseline, il proprietario, la decisione, le prove, il problema aperto e la data di approvazione. Utilizza una pagina o una transazione reale in modo che il team possa vedere le dipendenze, le eccezioni e il lavoro di manutenzione che segue il rilascio.
| Punto decisionale | Documentazione | Criterio di accettazione |
|---|---|---|
| Linea di base | Stato attuale osservato | Fonte e data registrate |
| Decisione | Opzione selezionata e motivazione | Rischio e pubblico considerati |
| Prova | Testare, documentare o misurare | Rivedibile e specifico della versione |
| Approvazione | Nome, ruolo e data | Tutti i criteri obbligatori sono soddisfatti |
Invia una richiesta a forma di produzione
Creare un client di integrazione lato server e archiviarne le credenziali nel gestore dei segreti di distribuzione. Invia JSON UTF-8 su HTTPS con un identificatore di origine stabile, revisione dell'origine, impostazioni internazionali richieste, modalità lingua e corpo del contenuto. Aggiungi una chiave di idempotenza che rimane la stessa quando viene ritentato il lavoro identico. Non esporre le credenziali nel codice del browser, nei file del repository, nei campi CMS, negli screenshot o nelle risposte agli errori visibili al client.
Inizia con una pagina di servizio rappresentativa ma non sensibile. Includere intestazioni, elenchi, collegamenti e una condizione legale o operativa in modo che la risposta eserciti il contratto sul contenuto reale. Rifiuta un identificatore di origine vuoto, impostazioni locali non supportate, modalità sconosciuta, corpo sovradimensionato o struttura non valida prima di chiamare API. Imposta una connessione esplicita e un timeout di risposta e propaga un identificatore di correlazione nei log dell'applicazione.
| Campo richiesta | Scopo | Validazione |
|---|---|---|
| IDorigine | Collegamento duraturo al record CMS | Obbligatorio, stabile, non personale |
| sourceRevision | Rileva risultati obsoleti | Obbligatorio e immutabile per la richiesta |
| locale e modalità | Seleziona le regole della lingua | Deve essere una combinazione abilitata |
| idempotenzaKey | Rende sicuri i tentativi | La stessa operazione utilizza la stessa chiave |
Convalidare il contratto di risposta completo
Considera uno stato HTTP riuscito solo come il primo controllo. Convalidare lo schema di risposta, l'identificatore del risultato, l'identificatore e la revisione dell'origine, le impostazioni locali, la modalità lingua, lo stato di elaborazione, i blocchi di contenuto, gli avvisi e la versione del modello o del set di regole, ove fornito. I valori enumerativi sconosciuti e i campi obbligatori mancanti non dovrebbero essere chiusi in un errore di integrazione rivedibile. Conserva gli avvisi accanto alla bozza perché possono identificare la terminologia, la qualità della fonte o i requisiti di revisione manuale.
Memorizza l'output generato come bozza di revisione separata anziché sovrascrivere la fonte approvata. Registra gli identificatori di richiesta e risultato, impostazioni di trasformazione, timestamp e un hash di integrità della revisione dell'origine. Visualizza un confronto per i revisori ed esegui l'escape di tutto l'output in base alla destinazione. Il markup generato costituisce un input non attendibile fino al completamento della convalida dello schema, della sanificazione, dei controlli di accessibilità e dell'approvazione umana.
- 1
Convalidare il payload in uscita rispetto a uno schema locale.
- 2
Invia la richiesta con intestazioni di autenticazione, timeout, idempotenza e correlazione.
- 3
Convalida lo stato, le intestazioni e il corpo della risposta rispetto al contratto bloccato.
- 4
Crea una bozza CMS separata collegata alla revisione esatta della fonte.
- 5
Indirizza avvisi e differenze nella coda di revisione editoriale corretta.
Gestisci gli errori senza duplicare o perdere il lavoro
Riprovare timeout, errori di connessione e limiti di velocità solo quando l'operazione è idempotente. Utilizzare il backoff esponenziale limitato con jitter e rispettare un ritardo tra i tentativi fornito dal server. Non riprovare gli errori di convalida, gli errori di autenticazione o le opzioni non supportate finché la configurazione non viene modificata. Posiziona le operazioni esaurite in una coda di messaggi non recapitabili con il riferimento all'origine, la categoria di errore sicura, il conteggio dei tentativi e il successivo team responsabile.
Separare lo stato rivolto all'utente dai dettagli diagnostici. Gli editori necessitano di stati chiari come in coda, in elaborazione, bozza pronta, azione richiesta e fallita con un passaggio successivo sicuro. Le operazioni necessitano di identificatori di richiesta, durata, categoria di stato e cronologia dei tentativi, ma non del testo di origine completo nei registri ordinari. Avviso relativo al tasso di errori sostenuti, all'aumento della durata della coda, agli errori di autenticazione, alle mancate corrispondenze dello schema e alle bozze la cui revisione dell'origine è cambiata durante l'elaborazione.
Ogni operazione riprovabile ha una chiave di idempotenza stabile.
Il backoff è limitato e rispetta le istruzioni relative al limite di velocità.
I log escludono credenziali e corpi di contenuto non necessari.
Gli elementi non recapitabili hanno un proprietario e una procedura di riproduzione.
Un risultato obsoleto non può sostituire silenziosamente una revisione del codice sorgente più recente.
Dimostrare l'integrazione prima del rilascio
Testa le richieste valide, ogni errore di convalida documentato, le credenziali scadute e revocate, i timeout, i limiti di velocità, l'invio duplicato, il completamento fuori ordine, l'evoluzione dello schema, la sanificazione e le modifiche all'origine durante l'elaborazione. Confermare che il monitoraggio identifichi ciascun errore e che un operatore addestrato possa riprodurre o chiudere l'elemento senza modificare il database. Esegui l'accessibilità e la revisione editoriale sulla bozza visualizzata anziché solo sulla risposta grezza.
Rilascio con credenziali limitate, tariffe definite e limiti di spesa, dashboard, proprietà degli avvisi e un interruttore di rollback che interrompe la nuova generazione senza influire sui contenuti pubblicati. Blocca la versione del contratto supportata e pianifica una revisione dell'aggiornamento. Il record di accettazione della produzione dovrebbe includere prove di test, approvazione di sicurezza, documentazione del flusso di dati, approvazione del revisore, istruzioni operative e ripristino riuscito di un lavoro deliberatamente fallito.
Ruoli, prove e approvazione
Mantenere la generazione separata dalla pubblicazione. Una risposta efficace è una bozza, non un'approvazione. Archiviare l'identificatore e la versione dell'origine, le impostazioni di trasformazione, l'identificatore del risultato, lo stato della revisione, l'approvatore e l'ora di pubblicazione. Quando la fonte cambia, contrassegna la versione linguistica per la revisione invece di sostituire silenziosamente il contenuto approvato. Ciò rende possibile il rollback e il controllo su tutte le piattaforme.
Operazioni e manutenzione
Il lavoro non termina con la pubblicazione. Collega la versione o la configurazione linguistica alla sua fonte, monitora la qualità e le misure del servizio e definisce criteri concreti di revisione. I fattori scatenanti includono modifiche alla fonte, modifiche legali, nuove esigenze del pubblico, domande di supporto ricorrenti, modifiche tecniche e incidenti. Un proprietario nominato valuta il trigger, apre una nuova revisione quando necessario e registra la rinnovata approvazione.
Lista di controllo per la pubblicazione
L'integrazione utilizza identificatori di origine durevoli.
Le credenziali vengono archiviate lato server e ruotate.
Vengono definiti il comportamento di timeout, nuovi tentativi e limite di velocità.
Le richieste ripetute sono idempotenti.
Il contenuto generato entra in uno stato di revisione.
Le modifiche all'origine invalidano o riapriranno la versione.
La navigazione linguistica funziona tramite tastiera e tecnologia assistiva.
Il monitoraggio copre errori, code, latenza e contenuto non aggiornato.