Aller au contenu

Conventions de l'API

Format des requêtes et des erreurs, validation stricte, identifiants, pagination, filtres, idempotence, CORS, tailles, délais et évolution de l'API.

RéférenceDéveloppeur
Voir en Markdown

Ces règles valent pour tous les endpoints de l'API publique https://api.wakastart.app/api. Les pages de domaine ne signalent que ce qui s'en écarte.

Format des requêtes et des réponses

  • Les corps de requête et de réponse sont en JSON, encodés en UTF-8. Envoyez Content-Type: application/json.
  • Les envois de fichiers utilisent multipart/form-data, avec le fichier dans le champ file.
  • Les dates sont au format ISO 8601, en UTC : 2026-10-23T09:12:44.512Z.
  • Les montants de paiement sont en centimes, dans des champs suffixés Cents : unitAmountCents: 4900 vaut 49,00.

Identifiants

La plupart des objets ont deux identifiants :

IdentifiantFormatExempleUsage
UUID36 caractères3f9a6c2e-1b7d-4c55-9e0a-6b2f4d8a1c01Identifiant technique, attendu dans les champs nommés …Id
WID6 caractères alphanumériquesEXCLI1Identifiant court, attendu dans les champs et chemins nommés …Wid ou :wid

Chaque paramètre indique lequel il attend. Quelques chemins acceptent l'un ou l'autre ; ils le signalent.

Validation des champs

L'API valide chaque corps de requête et chaque paramètre de requête contre la liste des champs déclarés :

  • un champ inconnu est refusé, avec 400 et le message property <nom> should not exist ;
  • un champ obligatoire absent, un type incorrect ou une contrainte non respectée donnent 400 ;
  • les paramètres de requête sont convertis vers le type attendu : ?limit=20 est lu comme le nombre 20, ?isActive=true comme un booléen.

N'envoyez donc que les champs documentés. Un client qui recopie un objet lu par l'API pour le renvoyer tel quel en modification sera refusé : construisez le corps de la modification champ par champ.

Erreurs

Toute erreur est renvoyée avec un statut HTTP 4xx ou 5xx et ce corps :

JSON
{
  "statusCode": 403,
  "message": "Droit applicatif requis : users.read",
  "error": "Forbidden",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/config/users"
}
ChampTypeDescription
statusCodeentierStatut HTTP, identique à celui de la réponse
messagechaîne ou tableau de chaînesCause de l'erreur. Pour une erreur de validation, un tableau avec un message par champ en défaut
errorchaîneLibellé générique de l'erreur. Indicatif : fondez votre traitement sur statusCode et message
timestampchaîne ISO 8601Date de l'erreur
pathchaîneChemin appelé, paramètres de requête compris

Exemple d'erreur de validation :

JSON
{
  "statusCode": 400,
  "message": ["property nickname should not exist", "email must be an email"],
  "error": "Bad Request",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/config/users"
}

Une erreur produite par un service interne de Wakastart vous est transmise avec son statut et son message d'origine. Une erreur inattendue donne 500 avec le message générique Internal server error, sans détail technique. Chaque statut est détaillé dans Codes d'erreur.

Pagination

Plusieurs formats de pagination coexistent selon le domaine. Chaque endpoint de liste indique le sien.

FormatParamètresRéponseUtilisé par
Page et taillepage (≥ 1, défaut 1), limit (1 à 100, défaut 20){ "data": [...], "meta": { "page", "limit", "total", "totalPages" } }Utilisateurs, clients, réseaux, équipes, profils, invitations
Page et taille, réponse à platpage (défaut 1), limit (1 à 100, défaut 20){ "data": [...], "total", "page", "limit", "totalPages" }Journal d'audit
Page et taille par pagepage (défaut 1), perPage (1 à 100, défaut 20){ "items": [...], "total", "page", "perPage" }Membres d'une organisation
CurseurstartingAfter (identifiant du dernier élément reçu), limit (1 à 100){ "data": [...], "hasMore", "nextCursor" }Factures et abonnements de l'utilisateur final
Aucune—Liste complèteThèmes, langues et traductions d'une application, membres d'une équipe, droits d'un profil

Pour parcourir une liste paginée par page, incrémentez page jusqu'à totalPages. Pour une liste à curseur, rappelez l'endpoint avec startingAfter égal à nextCursor tant que hasMore vaut true.

TypeScript
async function* allUsers(token: string) {
  for (let page = 1; ; page++) {
    const res = await fetch(`https://api.wakastart.app/api/config/users?page=${page}&limit=100`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    if (!res.ok) throw new Error(`API ${res.status}`);
    const { data, meta } = await res.json();
    yield* data;
    if (page >= meta.totalPages) return;
  }
}

Filtres et tri

  • Les listes de l'organisation acceptent des filtres de portée : partnerWid, networkWid, customerWid (6 caractères au plus) ou leurs équivalents UUID partnerId, networkId, customerId.
  • Pour un appel par clé API, ces filtres sont remplacés par la portée de la clé : son client, sinon son réseau, sinon son application.
  • Les filtres propres à chaque liste (isActive, status, action…) sont décrits avec l'endpoint.
  • L'API n'expose aucun paramètre de tri.

Idempotence

  • Les créations de paiement (sessions Checkout, achat de pack de crédits) exigent un champ idempotencyKey dans le corps, de 180 caractères au plus. Rejouer la même clé ne crée pas de seconde session. Générez une clé par intention d'achat, par exemple un UUID stocké avec la commande.
  • Les endpoints du module HDS acceptent l'en-tête Idempotency-Key sur POST, PUT et PATCH : la réponse est rejouée pendant 24 heures, avec l'en-tête X-Idempotency-Replayed: true.
  • Ailleurs, l'API n'offre pas d'idempotence : rejouer une création peut produire un doublon ou une erreur 409 (utilisateur ou invitation déjà existants). Avant de réessayer une création qui a échoué sur un délai dépassé, vérifiez par une lecture si l'objet existe.

Limites de débit

L'API limite le nombre de requêtes par adresse IP, sur trois fenêtres simultanées :

FenêtreLimite
1 seconde10 requêtes
1 minute100 requêtes
1 heure1 000 requêtes

Exceptions :

EndpointLimite
GET /api/invitations/verify/{token}, POST /api/invitations/accept/{token}60 par seconde, 600 par minute, 5 000 par heure
POST /api/token/enrichAucune limite

Au-delà, l'API répond 429 avec le message ThrottlerException: Too Many Requests. La réponse porte un en-tête par fenêtre dépassée, Retry-After-short, Retry-After-medium ou Retry-After-long, qui indique le nombre de secondes à attendre ; un navigateur ne peut pas les lire en appel croisé. Attendez ce délai, ou à défaut réessayez avec un délai croissant (1 s, 2 s, 4 s…). Si plusieurs instances de votre service sortent par la même adresse IP, elles partagent ces compteurs. Discovery a ses propres limites, décrites dans Discovery. Toutes les valeurs sont regroupées dans Limites et quotas.

CORS et appels depuis un navigateur

L'API publique n'accepte les appels d'un navigateur que depuis les origines que Wakastart a déclarées pour elle. Les en-têtes acceptés en appel croisé sont Content-Type, Authorization et x-api-key ; x-enriched-token n'en fait pas partie.

Nous recommandons d'appeler l'API depuis le serveur de votre application, qui ajoute le jeton de l'utilisateur. Si votre front doit l'appeler directement, envoyez le jeton Keycloak dans Authorization et demandez à Wakastart d'autoriser l'origine de votre front.

Tailles maximales

ContenuTaille maximale
Corps JSON ou formulaire1 Mo
Fichier envoyé à l'antivirus100 Mo
Fichier envoyé au module HDS100 Mo
Fichier CSV d'import d'utilisateurs2 Mo et 500 lignes
Jeton passé dans un corps de requête10 000 caractères

Un fichier qui dépasse la taille maximale est refusé avec 413.

Délais d'attente

L'API relaie chaque requête vers un service interne de Wakastart et attend sa réponse 5 à 10 secondes pour la plupart des endpoints, 60 secondes pour le module HDS et 120 secondes pour l'envoi d'un fichier à l'antivirus ou la traduction par IA. Fixez le délai de votre client HTTP au-dessus de ces valeurs.

Évolution de l'API

L'API publique n'a pas de numéro de version, ni dans l'URL, ni dans un en-tête. Les évolutions sont publiées dans les notes de version. Pour que votre intégration résiste aux ajouts :

  • ignorez les champs de réponse que vous ne connaissez pas ;
  • n'attendez pas un ordre précis des éléments d'une liste ;
  • traitez une valeur d'énumération inconnue comme un cas par défaut.

État de l'API

GET/api/healthz

Public. Indique que l'API répond.

Bash
curl -s https://api.wakastart.app/api/healthz
JSON
{
  "status": "ok",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "uptime": 86400,
  "service": "ws-back-api",
  "version": "1.0.0"
}