Paginierung, Wiederholung und Konkurrenz ohne Überraschungen.
Die folgenden übergreifenden Regeln gelten für alle Ressourcen und verhindern Duplikate, Endlosschleifen und fragile Integrationen.
Begrenzen und versetzen Sie die Paginierung
Listen verwenden einen Grenzwert von 1 bis 100 und einen Offset von Null. Fahren Sie fort, solange offset + data.length kleiner als pagination.total ist.
GET /api/v1/offers?status=approved&marketplace=amazon&limit=50&offset=100
{
"data": [ ... ],
"pagination": { "limit": 50, "offset": 100, "total": 384 },
"request_id": "req_01J..."
}Filter und Suche
statusFiltert nach dem kanonischen Status der Ressource.queryTextsuche; Behandeln Sie es als Korrespondenz, nicht als Kennung.marketplace / channelAkzeptiert den im Vorgang dokumentierten Anbietercode.daysMobiles Analysefenster zwischen 1 und 365 Tagen.from / toWenn vorhanden, verwenden Sie ISO 8601-Zeitstempel in UTC.Idempotenz und sichere Wiederholung
GET, PATCH und DELETE können mit derselben Bedeutung wiederholt werden. Kreationen, die über einen dokumentierten natürlichen Schlüssel verfügen, wie z. B. Angebot per URL und Empfang per externer Referenz, geben die vorhandene Ressource zurück, anstatt sie zu duplizieren.
Netzwerkausfälle, 429- und 5xx-Fehler mit exponentiellem Backoff und Jitter.
POST ohne natürlichen Schlüssel: Abfrage nach externer Kennung, bevor es erneut versucht wird.
400, 401, 402 und 403 bis korrekter Eintrag, Schlüssel, Plan oder Umfang.
Es verknüpft Ihren Anruf mit dem Audit und vereinfacht jede Untersuchung.