Idempotence, pagination et quotas
Trois règles rendent une intégration robuste : chaque création porte une clé d'idempotence, les listes se parcourent par curseur, et le débit reste sous le quota de la clé.
Qui peut le faire : tout outil qui appelle l'API.
Idempotence des créations#
Les deux créations, POST …/runs et POST …/audits, exigent l'en-tête Idempotency-Key.
| Règle | Détail |
|---|---|
| Format | 8 à 128 caractères ASCII visibles (sans espace) |
| Portée | propriétaire, clé API, projet et route |
| Même valeur, même corps | la première réponse est rejouée pendant 24 heures, avec Idempotent-Replayed: true |
| Même valeur, autre corps | 409 conflict |
| En-tête absent ou invalide | 422 invalid_request |
| Deux requêtes identiques simultanées | un seul effet |
Le corps est comparé après normalisation : l'ordre des champs JSON n'a pas d'importance.
curl -sS -i -X POST https://maintain.example/api/v1/projects/<projectId>/runs \
-H "Authorization: Bearer $MAINTAIN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: issue-42-2026-11-19" \
-d '{"repositoryId":"<repositoryId>","issueNumber":42}'HTTP/1.1 202 Accepted
Location: /api/v1/runs/<runId>
Idempotent-Replayed: false
Cache-Control: no-storeChoisir la valeur#
Dérivez la valeur de l'intention, pas de l'essai. Exemples : issue-42-2026-11-19, audit-hebdo-2026-w47, gha-<identifiant du workflow>. Après une coupure réseau, renvoyez exactement la même requête avec la même valeur : vous obtenez la réponse d'origine, sans second effet.
Verrous métier en plus#
L'idempotence ne remplace pas les règles métier. Une issue n'a qu'une exécution originale : même après 24 heures, redemander la même issue renvoie 409. Un audit déjà en file ou en cours pour un dépôt est renvoyé tel quel au lieu d'en créer un second. Pendant un arrêt global, les créations sont acceptées et attendent la levée (champ waiting) : voir Erreurs.
L'annulation POST /api/v1/runs/<runId>/cancel est idempotente par nature : la répéter ne change rien et n'exige pas d'Idempotency-Key.
Pagination#
Les listes sont triées par identifiant. Chaque page renvoie un champ next : passez sa valeur dans le paramètre after pour obtenir la page suivante. next: null signale la fin.
| Route | Taille de page | Paramètre limit |
|---|---|---|
GET /api/v1/projects | 50 | non accepté |
GET …/repositories | 1 à 50, 50 par défaut | oui |
GET …/runs | 1 à 50, 50 par défaut | oui |
GET …/audits | 30 | non accepté |
GET …/usage (entrées) | 100 | non accepté |
Un limit hors bornes, ou un after qui n'est pas un identifiant valide, renvoie 422. Pour /usage, after est un curseur opaque : réutilisez la valeur next telle quelle.
after=""
while :; do
page=$(curl -sS "https://maintain.example/api/v1/projects/<projectId>/runs?limit=50${after:+&after=$after}" \
-H "Authorization: Bearer $MAINTAIN_API_KEY")
echo "$page" | jq -r '.runs[] | "\(.id) \(.status)"'
after=$(echo "$page" | jq -r '.next // empty')
[ -z "$after" ] && break
doneQuotas#
Le quota est compté par clé et par projet, sur une fenêtre fixe d'une minute. Il est de 120 requêtes par minute au plus ; l'exploitant de l'instance peut l'abaisser avec MVP_API_RATE_LIMIT_PER_MINUTE, jamais le relever. Les appels à GET /api/v1/projects sont comptés pour la clé, hors projet.
Au-delà, la réponse est 429 rate_limited avec l'en-tête Retry-After, en secondes, jusqu'à la fin de la minute en cours. Les requêtes refusées comptent aussi dans la fenêtre : attendez avant de réessayer.
Ce quota s'ajoute aux limites métier : plafonds de jetons, budgets et concurrence des exécutions. Voir Budgets et plafonds.
Pour continuer#
Interprétez chaque refus : Erreurs.