Compilare un brief d’integrazione: l’esempio di un report

Descriva un’integrazione attraverso un flusso completo prima di confrontare le offerte. «Il portale ha bisogno di una connessione API» lascia aperte le domande sui dati trasferiti, sul completamento del lavoro e su chi gestisce un errore. Un brief compilato permette di discutere queste decisioni.

Definire un flusso per la prima consegna

In questo progetto fittizio, un portale richiede un report PDF mensile a un servizio documentale. Nomi, campi e risposte sono esempi nostri, non l’API di un fornitore.

Così diventano visibili anche le richieste aggiuntive: una futura funzione e-mail sarebbe un passaggio separato con una propria gestione degli errori. Non scompare dentro la parola «connessione».

Specificare valori e significato degli input

Per POST /report-jobs viene concordato questo contenuto di esempio:

{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}

L’identificativo della richiesta indica questa richiesta di creazione. Progetto e modello sono riferimenti stabili; il periodo è qui un mese di calendario nel formato anno–mese. I nomi visualizzati o un periodo scritto liberamente non sostituiscono questi valori. Il portale deve chiarire con il servizio documentale quali modelli sono approvati.

L’accesso al lavoro, allo stato e al file è limitato al progetto autorizzato. Conoscere un link non consente da solo il download. Il brief specifica ruoli e metodo di accesso; token e password reali restano fuori dal documento.

Descrivere separatamente accettazione e risultato

Dopo la registrazione duratura della richiesta, il servizio di esempio risponde con HTTP 202 e Location: /report-jobs/J-52:

{"jobId":"J-52","status":"queued"}

MDN descrive 202 come l’accettazione di un’elaborazione non ancora completata. Il nostro contratto prevede quindi gli stati queued (in coda), running (in elaborazione), succeeded (riuscito) e failed (fallito). Il lavoro riesce solo quando il file è creato e, al completamento, recuperabile con l’autorizzazione necessaria. Microsoft descrive una consultazione separata dello stato per i lavori asincroni; i nomi specifici degli stati sono una nostra scelta.

Lo stesso identificativo con contenuto identico nello stesso ambito autorizzato rimanda allo stesso lavoro. Per contenuti diversi, l’esempio prevede HTTP 409. Questa regola di ripetizione va implementata e verificata; il nome del campo non crea idempotenza.

Compilare quattro casi di accettazione prima dell’implementazione

Nell’ultimo caso il team di piattaforma controlla il modello. Una nuova richiesta corretta riceve un nuovo identificativo; il lavoro fallito resta tracciabile. Se è indisponibile soltanto la consultazione dello stato, il portale indica che lo stato attuale è sconosciuto, senza dichiarare successo o fallimento.

Chiarire le questioni operative prima di impegnarsi

Aggiunga volume di lavori previsto, dimensione tipica dei file, attesa ammissibile, intervallo di consultazione e conservazione di file e stati in base all’uso effettivo. Questi valori restano aperti nell’esempio e vanno chiariti prima di un impegno attendibile. Una durata stimata non viene trattata come una proprietà misurata.

Una descrizione OpenAPI può precisare operazioni, input e risposte attese. Devono essere stabilite anche la definizione applicativa del risultato e le responsabilità dei team. Con i casi definiti, i team di portale e piattaforma possono valutare la stessa consegna.

Fonti

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses