Cinque errori critici di integrazione API all'avvio

Errore numero 1. Nessuna idempotenza e «tempesta» di retroscena

Sintomi: prese di ordini/pagamenti, variazioni di importo, rimborsi controversi, alert DLQ in aumento.

Radice: la riconsegna di richieste/webhoop e flappy di rete sono normali. Se l'operazione Crea/Cancella non è idipotente, i retrai moltiplicano i danni.

Come è corretto

Idempotency-Key/« operation _ id »per tutti i metodi non sicuri (POST/PATCH).

Indice univoco nel database dì operation _ id ". Ripetizione, restituisci l'ultimo risultato.

Webhoop tramite tabella Inbox («event _ id + firma»). Gli eventi in uscita sono Outbox.

Retrai: massimo 1-2 volte, esponente + jitter, solo per operazioni sicure.

Convenzione HTTP (esempio):

http
POST /v1/payments
Idempotency-Key: ik_f35a2
Content-Type: application/json

{"amount": 5000, "currency": "EUR", "source": "card_..."}

Protezione SQL (semplificata):

sql
ALTER TABLE payments ADD CONSTRAINT uniq_op UNIQUE (operation_id);

Retrai con jitter (pseudocode):

python for i in range(2):
try: return call_api(payload, timeout=0. 6)
except Timeout:
sleep(0. 05 2i + random. uniform(0, 0. 05))
raise UpstreamUnavailable

Assegno foglio:

Tutta la logica «moneta/creatrice» ha «operation _ id» e uniq-indice.
Webhoop in entrata solo tramite Inbox con il worker idipotente.
SDK client installa automaticamente Idempotency-Key.

Errore numero 1. Timeout/retrai contro SLO: surriscaldamento delle dipendenze

I sintomi sono che il p95 parte improvvisamente, le code crescono, il circuito breaker «fluttua».

Radice: la risposta SLO totale è di 400-600 ms, mentre i timeout per API esterne sono di 1-2 s e anche retrai x 3. Si fa più a lungo che si può e si fa dipendenza ripetutamente.

Come è corretto

Budget-timing: se SLO 400 ms, upstream-time: 250-300 ms; timeout totale della richiesta SLO.

Limits/Backpressure: semafori/worker-pool per chiamate a ogni dipendenza. Il → 429/503 è pieno.

Circuito breaker: 'open', a time-out/5xx, 'half-open', dosato.

Accession control: limita il parallelismo (per flusso, per endpoint/PSP).

Esempio (Go):

go sem: = make (chan struttt {}, 64 )//limite di concorrenza per PSP func callPSP (ctx text. Context, req Req) (Res, error) {
select {
case sem <- struct{}{}:
defer func(){ <-sem }()
c, cancel:= context. WithTimeout(ctx, 300time. Millisecond)
defer cancel()
return psp. Do(c, req)
default:
return Res {}, ErrBusy/errore immediato al posto della coda senza fine
}
}

Assegno foglio:

Timeout più breve di SLO; Retrai 2; C'è un jitter.
Pool/semafori per API esterne; circuito breaker con metriche.
I percorsi «busy» restituiscono 429/Retry-After, non le connessioni.

Errore numero 3. Sicurezza debole: firme web, segreti, TLS

I sintomi sono: webhook'estranei ', webhook', segreti in codice/codice, rischi MITM.

Radice: nessun controllo firma/freschezza, i segreti vivono in file uv, vecchi TLS e titoli deboli.

Come è corretto

Firma HMAC-SHA256 + X-Timestamp (finestra ≤ 5-10 min), confronto rigoroso della firma.

mTLS per le integrazioni critiche o IP allow-list.

Rotazione dei segreti tramite Vault/Cloud KMS; Minimo diritti; Controllo della sottrazione.

TLS 1. 2/1. 3 only, HSTS, CORS corretti (elenco ristretto delle origini).

Convalida firma (Python):

python def verify(sig_hdr, ts_hdr, body, secret):
if abs(time. time() - int(ts_hdr)) > 600: raise Expired()
calc = hmac. new(secret, (ts_hdr + "." + body). encode(), hashlib. sha256). hexdigest()
if not hmac. compare_digest(calc, sig_hdr): raise BadSig()

Assegno foglio:

Tutti i webhoop sono firmati e controllati; la finestra di freschezza è limitata.
I segreti in KMS/Vault, ci sono rotazione e controllo.
TLS/HSTS abilitati; KORS a punti; Se necessario.

Errore numero 4. Contratto-drift, schema «vivere la propria vita»

Sintomi: il profumo cadeva «solo in una parte dei clienti», 500/422 nei reparti, diverse versioni SDK e API litigano.

Radice: nessuna descrizione rigorosa dei contratti, cambiamenti incompatibili di ritorno, campi silenziosi, senso diverso per gli stessi nomi.

Come è corretto

Contratto-1: OpenAPI/AsyncAPI + generazione di server/client; per gli eventi - Avro/Protobuf + Schema Registry.

Versioning: «v1 → v2» (URI/heder), piano di deprecazione, periodo di grace.

Backward-compat: solo modifiche additive nelle release minori; impedisce di eliminare o rinominare senza v-bump.

Test contrattuali: Pact/Buf - provider/consumatore sono controllati in CI.

Esempi:

yaml
OpenAPI: tipo di somma nitido in unità minori amount _ minor:
type: integer minimum: 0 descrizione: Importo in unità minime di valuta (intero)

Assegno foglio:

I contratti sono memorizzati in git, CI valuta/rompe in caso di incompatibilità.
Registri degli eventi, compatibilità «back/forward».
La pagina doc delle modifiche, le date di deprecazione, lo stand di prova per i partner.

Errore numero 5. Lancio cieco: niente metriche/fogli/roulotte e scarponi di sabbia

I sintomi sono: «Non si vede niente», il supporto è esausto, il debag è in vendita.

Non hanno attivato l'osservazione, non c'è sintetica, la sabbia è stata testata a parole.

Come è corretto

Metriche RED/USE: rate/errore/latency su ogni endpoint, percorsi/metodi.

Correlazione: «trace _ id» in tutti i fogli e le risposte; Il legamento è zapros↔vebkhuk.

Sintetica: provini health (login/deposit-sabbia), monitoraggio SLA T + 60 per webhoop.

Cassetta di sabbia/stage: chiavi/domini completamente isolati, PSP fittizi, registrazioni «non compaiono nei rapporti».

Risposta trace:

http
HTTP/1. 1 202 Accepted
Trace-Id: 7f2b3d8e9c1a4
Location: /v1/ops/req_42/status

Assegno foglio:

Metriche RED/USE, dashboard, alert (sintomi + cause).
Trade end-to-end; logi JSON, senza PII, con «trace _ id».
Sintetica dalle regioni chiave; La sabbia è obbligatoria, le chiavi sono diverse.

Piano Prelounch (T-7) T-0

T-7 giorni:

Contratto-scan finale: se non ci sono modifiche incompatibili; diagrammi freeze.
Segreti/certificati: controlla rotazione, disponibilità, criteri KMS.
Sintetica 24 x 7, gli alert sono legati a on-call.

T-3 giorni:

Mini-prova di carico (burst 2-5 min): p95/pool/coda nella zona verde.
DRY-RUN webhoop (ripetizioni, 5xx, jitter), controllo DLQ.
I contatti L1/L2, il canale war-room.

T-0:

Traffico canario 5% → 25% → 50% su gate SLO; pronto per il rollback.
Sono abilitati kill-switch/feature-flags sui file a rischio.
La war room è attiva e lo stato dei modelli è pronto.

Piano Rollback (se qualcosa è andato storto)

1. Sposta il traffico sulla versione/percorso stabile precedente.

2. Disattiva le modifiche contestate.

3. Stabilizzare le code/pool, fermare i retrai durante la tempesta.

4. Post-incidente - Assemblare timeline, radici, attività (fix anteriori/fissi del contratto).

Tabella automatica di avvio (breve)

Blocco	Domanda	Sì/No
Idampotenza	Tutti i metodi «creatori» hanno Idempotency-Key/« operation _ id »e uniq-index?
Retrai/timeout	Timeout più breve di SLO; Retrai ≤2; Il jitter è acceso?
Sicurezza	Le webhocks sono firmate, la finestra di freschezza delle mine, i segreti di KMS?
Contratti	OpenAPI/AsyncAPI registrati, CHI cattura l'incompatibilità?
Osservabilità	RED/USE, roulotte, sintetica T + 60, cassetta di sabbia isolata?
Rollback	C'è un pulsante di ripristino/kill-switch, un piano di comunicazione?

Frequenti «e se...»

... il provider non supporta Idempotency-Key?

Memorizza «hash (body)» + «partner _ richiest _ id» e inserisci la tua idimpotenza.

... i webhook a volte arrivano «prima» della risposta?

Allineare in «operation _ id» e mantenere temporaneamente lo stato «unknown»; il reconciler periodico chiuderà le soluzioni temporanee.

... dobbiamo sostenere i vecchi clienti e i nuovi clienti?

Versionare endpoint's ('/v1 'e '/v2'), ruotare in base al titolo/URI, mantenere la compatibilità backward per un minimo di N mesi.

Curriculum

I fallimenti delle integrazioni sono quasi sempre la stessa: nessuna idepotenza, timeout e retrai errati, la firma scarsa dei webhook, la deriva dei contratti e la mancanza di visibilità. Fissate i contratti in anticipo, attivate l'osservazione, fissate i limiti/beckprescher, firmate tutte le interazioni esterne e eseguite il sintetico. Anche se i soci fallissero, il vostro comunicato rimarrebbe gestito - senza i soldi persi nei retrai e senza l'insonnia di tutta la squadra.