Intégration API

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ègleDétail
Format8 à 128 caractères ASCII visibles (sans espace)
Portéepropriétaire, clé API, projet et route
Même valeur, même corpsla première réponse est rejouée pendant 24 heures, avec Idempotent-Replayed: true
Même valeur, autre corps409 conflict
En-tête absent ou invalide422 invalid_request
Deux requêtes identiques simultanéesun seul effet

Le corps est comparé après normalisation : l'ordre des champs JSON n'a pas d'importance.

bash
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
HTTP/1.1 202 Accepted
Location: /api/v1/runs/<runId>
Idempotent-Replayed: false
Cache-Control: no-store

Choisir 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.

RouteTaille de pageParamètre limit
GET /api/v1/projects50non accepté
GET …/repositories1 à 50, 50 par défautoui
GET …/runs1 à 50, 50 par défautoui
GET …/audits30non accepté
GET …/usage (entrées)100non 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.

bash
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
done

Quotas#

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.