Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

Relancer en toute sécurité avec une clé d'idempotence

Cette recette montre comment relancer en toute sécurité l'appel de démarrage d'import après une défaillance réseau ou une erreur ambiguë. L'en-tête Idempotency-Key sur POST /api/v1/monitoring/loan/imports fait renvoyer au second appel le même identifiant d'import que le premier, avec une URL de téléversement nouvellement générée — aucun import en double n'est créé.

Quand l'utiliser

Chaque fois que vous ne savez pas si l'appel précédent de démarrage d'import a abouti. Les deux cas canoniques :

  • Votre client HTTP a déclenché un délai d'expiration avant l'arrivée de la réponse. La requête a pu atteindre Waafir et démarrer un import ; vous ne le savez pas.
  • Vous avez reçu une erreur 5xx d'une interface non idempotente et voulez relancer sans risquer de travail en double.

La convention commune à toute la plateforme veut que chaque endpoint de modification accepte Idempotency-Key — ici l'endpoint de démarrage d'import, ailleurs l'endpoint d'export et les endpoints de modification d'audit. Utilisez une nouvelle clé par opération logique ; réutilisez-la pour toutes les relances de la même opération. Un schéma courant consiste à générer un UUID v4 une fois par intention « lot d'import quotidien » et à le conserver dans l'état de votre tâche jusqu'à la réussite de l'appel.

Le contrat

  • L'en-tête est Idempotency-Key: <your-string>. 255 caractères maximum.
  • Le corps accepte également un champ idempotencyKey ; l'en-tête est prioritaire lorsque les deux sont présents. Privilégiez l'en-tête — c'est l'emplacement canonique sur toute la plateforme.
  • Un appel répété avec le même (orgId, idempotencyKey) renvoie :
    • le même importId,
    • reused: true dans la réponse,
    • une URL de téléversement nouvellement générée (l'URL d'origine expire ; la nouvelle est celle qu'il faut utiliser).
  • Un appel répété avec un corps différent mais la même clé est rejeté ; la clé est liée à la structure de la requête d'origine.

La recette

# curl — start an import with an idempotency key, then retry safely
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Generate a fresh key per logical batch intent; keep it stable across retries.
IDEMPOTENCY_KEY="loan-import-2026-05-22-$(uuidgen)"

start_import() {
  curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
    -H "Authorization: Bearer ${PAT}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)"
}

# First call. If the network bombs out we have no idea whether the
# request landed — but the same key on the next attempt guarantees no
# duplicate import.
RESULT=$(start_import || true)

if [ -z "${RESULT}" ] || ! echo "${RESULT}" | jq -e .importId > /dev/null; then
  echo "first call ambiguous; retrying with the same idempotency key…"
  RESULT=$(start_import)
fi

echo "${RESULT}" | jq '{importId, reused, uploadUrl}'
# On a retry, reused == true; the importId matches the first call's; the
# uploadUrl is fresh.
// TypeScript — retry start-import safely with an Idempotency-Key
import { randomUUID } from "node:crypto";
import { statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-2026-05-22.ndjson";
const idempotencyKey = `loan-import-2026-05-22-${randomUUID()}`;

async function startImport() {
    return fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${PAT}`,
            "Content-Type": "application/json",
            "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({
            kind: "loan",
            filename: NDJSON_FILE,
            sizeBytes: statSync(NDJSON_FILE).size,
        }),
    });
}

// Retry up to 3 times on transient failures; the same key makes this safe.
let lastError: unknown;
let result: { importId: string; reused: boolean; uploadUrl: string } | null = null;
for (let attempt = 1; attempt <= 3; attempt++) {
    try {
        const res = await startImport();
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
        result = (await res.json()) as typeof result;
        break;
    } catch (err) {
        lastError = err;
        console.warn(`attempt ${attempt} failed; retrying with same idempotency key`, err);
        await new Promise((r) => setTimeout(r, 1_000 * attempt));
    }
}

if (!result) throw lastError;
console.log({ importId: result.importId, reused: result.reused, uploadUrl: result.uploadUrl });
# python — retry start-import safely with an Idempotency-Key
import os
import uuid
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-2026-05-22.ndjson")

idempotency_key = f"loan-import-2026-05-22-{uuid.uuid4()}"

def start_import():
    return requests.post(
        f"{BASE_URL}/api/v1/monitoring/loan/imports",
        headers={
            "Authorization": f"Bearer {PAT}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "kind": "loan",
            "filename": NDJSON_FILE.name,
            "sizeBytes": NDJSON_FILE.stat().st_size,
        },
        timeout=30,
    )

# Retry up to 3 times on transient errors. The same key makes a second
# successful call a guaranteed replay of the first.
last_exc = None
result = None
for attempt in range(1, 4):
    try:
        response = start_import()
        response.raise_for_status()
        result = response.json()
        break
    except requests.RequestException as exc:
        last_exc = exc
        print(f"attempt {attempt} failed; retrying with same idempotency key: {exc}")
        time.sleep(attempt)

if result is None:
    raise RuntimeError("all retries exhausted") from last_exc

print({
    "importId": result["importId"],
    "reused": result["reused"],
    "uploadUrl": result["uploadUrl"],
})

Ce qu'il faut vérifier

Lors d'un premier appel réussi, reused vaut false. Lors de tout appel ultérieur avec la même clé, reused vaut true et importId est égal à celui du premier appel. L'uploadUrl est régénérée à chaque appel, de sorte que relancer après l'expiration d'une URL périmée est sans risque — utilisez toujours l'URL de la réponse la plus récente.

Si vous relancez avec un corps de requête différent et la même clé, l'API renvoie une erreur indiquant que la clé est liée à une structure de requête incompatible ; changez de clé pour la nouvelle intention.