Pagination, erreurs et polling

Cette page couvre les contrats transverses partagés par tous les endpoints : la pagination, la forme d'erreur uniforme et — l'API n'ayant pas de webhooks — la façon d'interroger l'API pour détecter les changements.

Pagination par offset

Presque tous les endpoints de liste utilisent le même contrat de pagination par offset, avec deux paramètres de requête :

Les valeurs hors bornes sont silencieusement ramenées dans l'intervalle, jamais rejetées. ?limit=10000 ne renvoie pas de 400 — c'est traité comme limit=200. Le plafond absolu est toujours de 200 éléments par appel.

Une réponse de liste paginée ressemble à ceci :

{
  "data": [ ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 342
  }
}

• data — la page d'éléments.
• pagination.limit / pagination.offset — renvoient les valeurs effectives (après bornage) qui ont été appliquées.
• pagination.total — le nombre total d'éléments correspondant à la requête, toutes pages confondues. Utilisez-le pour savoir quand arrêter de paginer.

Pour parcourir toutes les pages, incrémentez offset de limit à chaque appel jusqu'à ce que offset >= total :

async function listAll(path, apiKey, limit = 200) {
  const items = [];
  let offset = 0;
  let total = Infinity;
 
  while (offset < total) {
    const url = new URL(`https://app.kabeen.io/public/v1${path}`);
    url.searchParams.set("limit", limit);
    url.searchParams.set("offset", offset);
 
    const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
    const body = await res.json();
 
    items.push(...body.data);
    total = body.pagination.total;
    offset += limit;
  }
 
  return items;
}

Exception : catalogue applicatif — pagination par numéro de page

GET /application-catalog recherche dans le catalogue de référence global, indépendant de l'espace de travail, qui pagine par numéro de page plutôt que par offset/limit :

{
  "data": [ ],
  "total": 1204,
  "page": 1
}

Demandez la page suivante avec ?page=2, ?page=3, etc. (base 1, défaut 1). Il n'y a pas de paramètre limit pour cet endpoint — la taille de page est fixée par le service de catalogue. Arrêtez-vous dès que data revient vide.

Exception : journal d'audit — pagination par curseur

GET /audit-log est en ajout continu et à fort volume : il utilise donc une pagination par jeu de clés (curseur) plutôt que par offset, du plus récent au plus ancien :

{
  "data": [ ],
  "total": 58213,
  "nextCursor": "2026-07-21T09:12:03.441Z,3f9c...",
  "hasMore": true
}

• nextCursor est un jeton opaque — traitez-le comme une boîte noire, ne le parsez pas et ne le construisez pas vous-même.
• Renvoyez-le via ?cursor=... pour obtenir la page suivante.
• hasMore indique s'il faut continuer ; nextCursor n'a de sens que tant que hasMore vaut true (il est nullable et absent sur la dernière page).
• total reste le décompte global correspondant à vos filtres, mais pilotez la boucle avec hasMore/nextCursor, pas en comparant un offset à total.

Exception : listes de sous-ressources — tableaux nus

Certains endpoints de sous-ressources renvoient un simple tableau JSON sans aucune enveloppe — pas de wrapper data, pas de pagination. Il s'agit de petites collections bornées rattachées à une ressource parente unique. Exemples : GET /applications/{id}/owners, GET /applications/{id}/tags, GET /applications/{id}/teams, GET /applications/{id}/comments, GET /servers/{id}/owners, GET /servers/{id}/tags, GET /networks/{id}/routers, GET /routers/{id}/networks, GET /routers/{id}/tags. Un appel à l'un d'entre eux renvoie directement [ ... ].

Gestion des erreurs

Chaque réponse d'erreur émise par le traitement des requêtes de l'API elle-même — chaque 400, 403, 404, 409, 422 et 5xx, sur chaque endpoint — a la même forme JSON :

{
  "code": "not_found",
  "message": "server not found",
  "status": 404
}

Codes de statut

Le cas particulier du 401

Chaque statut ci-dessus revient avec le corps JSON uniforme — sauf 401. L'authentification est appliquée avant que la requête n'atteigne la gestion d'erreurs de l'API : un véritable 401 revient donc avec :

• Statut 401, corps vide (pas de JSON — n'essayez pas d'en extraire code/message/status).
• Un en-tête de réponse WWW-Authenticate: Bearer realm="kbine", error="invalid_token".

Si votre client attend toujours un corps d'erreur JSON, traitez 401 à part (ou branchez simplement sur le statut seul).

400 et 422 se recouvrent dans l'esprit mais pas dans l'intention : 400 signifie que l'API n'a même pas pu analyser ce que vous avez envoyé ; 422 signifie que l'analyse a réussi mais que le sens est invalide compte tenu de l'état actuel de la ressource.

Valeurs de code connues

De nouveaux codes pourront être ajoutés dans de futures versions — prévoyez toujours un cas par défaut.

Bonnes pratiques : vérifiez d'abord le statut HTTP, branchez sur code (jamais sur message), journalisez message pour le diagnostic, et repliez-vous sur status pour tout code que vous ne reconnaissez pas.

Pas de webhooks — interrogez l'API

L'API n'offre pas de webhooks, d'abonnements à des événements ni de mécanisme de push/callback dans cette version. Elle fonctionne uniquement en requête/réponse (pull). Deux approches complémentaires couvrent presque tous les cas d'usage « détecter un changement » :

1. Interroger le journal d'audit (ce qui se rapproche le plus d'un flux de changements)

GET /public/v1/audit-log (scope audit_log:read) est aujourd'hui la meilleure approximation d'un flux d'événements offerte par l'API. Il renvoie les événements d'audit de l'espace de travail, du plus récent au plus ancien, et prend en charge le filtrage par plage de dates (from/to), par acteur (actorId), par catégorie/action (category, actions répétable), par ressource (resourceType, resourceId), la recherche en texte libre (query) et la pagination par curseur (limit max 200 + cursor).

Interrogez-le à intervalle régulier, en avançant avec nextCursor tant que hasMore vaut true, et persistez le dernier curseur (ou le timestamp du dernier événement traité) entre les exécutions :

cursor = load_last_cursor()
loop:
  page = GET /audit-log?limit=200&cursor={cursor}
  for event in page.data:
    handle(event)
  if page.nextCursor:
    cursor = page.nextCursor
    save_cursor(cursor)
  if not page.hasMore:
    sleep(poll_interval)

2. Comparer les horodatages des ressources

La plupart des ressources portent un horodatage que vous pouvez comparer à un passage précédent :

C'est plus grossier que le journal d'audit — cela vous dit que quelque chose a changé, pas quoi ni qui — mais c'est simple et cela fonctionne même pour les ressources sans catégorie d'audit dédiée.

Polling efficace

• Respectez le plafond de taille de page (200) et demandez la plus grande page que votre intervalle peut confortablement traiter.
• Choisissez un intervalle raisonnable. Un intervalle de 1 à 5 minutes est un bon défaut pour la plupart des intégrations.
• Persistez toujours votre curseur/horodatage avant de traiter la page, afin qu'un crash ou un redémarrage reprenne au bon endroit plutôt que de retraiter ou de sauter des événements.
• Préférez le journal d'audit quand vous avez besoin de savoir « ce qui a changé » — il connaît l'acteur, l'action et la ressource.