Pagination, répétition et compétition sans surprises.
Les règles transversales ci-dessous s'appliquent à toutes les ressources et évitent les duplications, les boucles infinies et les intégrations fragiles.
Limiter et décaler la pagination
Les listes utilisent une limite de 1 à 100 et un décalage à partir de zéro. Continuez tant que offset + data.length est inférieur à pagination.total.
GET /api/v1/offers?status=approved&marketplace=amazon&limit=50&offset=100
{
"data": [ ... ],
"pagination": { "limit": 50, "offset": 100, "total": 384 },
"request_id": "req_01J..."
}Filtres et recherche
statusFiltre par l'état canonique de la ressource.queryRecherche textuelle ; traitez-le comme une correspondance et non comme un identifiant.marketplace / channelAccepte le code fournisseur documenté dans l'opération.daysFenêtre d'analyse mobile comprise entre 1 et 365 jours.from / toLorsqu'ils sont présents, utilisez les horodatages ISO 8601 en UTC.Idempotence et répétition sûre
GET, PATCH et DELETE peuvent être répétés avec la même signification. Les créations qui ont une clé naturelle documentée, comme l'offre par URL et la réception par référence externe, renvoient la ressource existante au lieu de la dupliquer.
Pannes de réseau, erreurs 429 et 5xx avec interruption exponentielle et gigue.
POST sans clé naturelle : interrogation par identifiant externe avant de réessayer.
400, 401, 402 et 403 jusqu'à la saisie, la clé, le plan ou la portée corrects.
Il relie votre appel à l’audit et simplifie toute enquête.