12

Comprendre les API

Lire, tester et gérer les erreurs

Module 126 min de lectureMis à jour le 20 novembre 2026

Une API est un contrat. Elle dit ce qu’elle attend, ce qu’elle renvoie et ce qui se passe quand quelque chose ne va pas. La plupart des intégrations cassent parce que ce contrat a été lu en diagonale.

Nous allons décortiquer une requête, parler d’authentification, de pagination, de limites de débit et d’idempotence. Puis nous construirons une requête à la main pour voir ce que les bibliothèques cachent. Tester petit avant de brancher la production.

A. Anatomie d’une Requête HTTP

POST https://api.stripe.com/v1/payment_intents
Authorization: Bearer sk_test_4eC39H...
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=eur&automatic_payment_methods[enabled]=true
1. Method (Verbe)

GET (Lire), POST (Écrire), PUT/PATCH (Modifier), DELETE (Supprimer).

2. Endpoint (URL)

L’adresse du guichet unique.

3. Headers

Les métadonnées (Auth, Format). Le "sticker sur l’enveloppe".

4. Body (Payload)

Le contenu du colis (souvent en JSON, parfois en formulaire comme Stripe ci-dessus).

Une manière simple de lire une requête : la méthode dit ce que l’on veut faire, l’URL dit à qui, les en-têtes donnent les instructions de service, le corps contient la commande. La réponse a la même structure : un statut, des en-têtes, un corps. Un 200 ne garantit pas que le contenu est correct ; un 400 ne dit pas toujours quel champ est fautif. Lisez le corps d’erreur, pas seulement le code.

Les en-têtes de réponse contiennent souvent des informations précieuses : limite de débit restante, identifiant de requête, pagination suivante, type de contenu. Les ignorer, c’est perdre la moitié du contrat. En cas d’incident, l’identifiant de requête est ce qui permet au fournisseur de retrouver l’appel exact.

B. Les Types d’Authentification

Basic Auth / API Key

Simple & Rapide.

Authorization: Api-Key 12345

Souvent passé en Header ou en Query Param (?key=123).

OAuth2 (Le Cauchemar nécessaire)

Sécurisé & Temporaire.

  • 1. Redirection vers Google ("Accepter ?").
  • 2. Reçoit un code.
  • 3. Échange code contre Access Token (valide 1h).
  • 4. Utilise Refresh Token pour renouveler.
Heureusement, n8n gère ça pour vous !

Un token est un mot de passe qui porte des droits. Trois règles évitent la plupart des incidents : stockez-le dans un coffre, pas dans le JSON du workflow ; donnez-lui le plus petit périmètre possible ; prévoyez son expiration et son renouvellement. Un jeton de test n’a rien à faire en production, même « pour aller plus vite ». La rotation d’un secret doit être une procédure testée, pas une improvisation le jour où il fuite.

Polling vs Webhooks :
  • Polling (L’enfant impatient) : "On est arrivé ? On est arrivé ?" (Demande toutes les 5min). Gaspille des ressources.
  • Webhook (Le coup de fil) : "Appelle-moi quand tu arrives." Le serveur vous notifie instantanément.
Préférez toujours les Webhooks quand c’est possible.

C. Traduire le "cURL"

Les docs donnent souvent des exemples en ligne de commande (cURL). Vous devez savoir les lire pour les mettre dans n8n.

curl -X POST https://api.site.com/users \
-H "Authorization: Bearer 123" \
-H "Content-Type: application/json" \
-d '{"name":"Bob"}'
  • -X POST -> Méthode
  • -H "..." -> Header
  • -d '...' -> Body (Data)

Atelier : construire une requête HTTP

Remplissez les champs, puis lisez la requête brute. Aucun appel réseau n’est effectué : l’atelier sert à comprendre la méthode, l’URL, les en-têtes et le corps.

Réflexes doc API

Avant de brancher le premier nœud HTTP, repérez : les statuts (200, 400, 429), la pagination, les limites de débit et l’idempotence. C’est ce qui sépare une démo d’une intégration qui tient en prod.

Tester sans casser

  • Commencer par une lecture : un GET sur une seule ligne, avec une clé de test.
  • Limiter le volume : limit=1 ou per_page=1 avant de boucler sur mille éléments.
  • Utiliser un bac à sable : beaucoup d’API proposent un environnement de test. Vérifiez qu’il ne pointe pas vers les données de production.
  • Éviter les DELETE en production pendant la mise au point. Si vous devez tester une suppression, créez d’abord un enregistrement jetable.
  • Journaliser l’identifiant de requête : c’est la première chose que le support demandera.
  • Prévoir l’idempotence : une écriture rejouée après un timeout ne doit pas créer deux fois la même ressource.

D. Pagination : offset ou curseur

Une API ne renvoie jamais tout. Deux conventions coexistent, et le choix change la fiabilité de votre synchronisation.

Offset / limit

?limit=100&offset=200. Simple, lisible, adapté à un export ponctuel. Si une ligne est insérée pendant la boucle, vous pouvez en sauter ou en voir deux fois.

Curseur

?limit=100&starting_after=cli_123. Stable quand les données bougent, préféré pour une synchronisation régulière. Le curseur est opaque : ne le construisez pas vous-même.

boucle_de_pagination.txt
curseur = null
repeter :
    page = api.lister(limite=100, apres=curseur)
    traiter(page.items)
    curseur = page.next_cursor
    si curseur est null       -> sortir
    si pages > 200           -> alerter et sortir
Le garde-fou : plafonnez toujours le nombre de pages. Une API qui renvoie le même curseur, ou une erreur transformée en page vide, peut faire tourner une boucle toute la nuit.

E. Erreurs, retries et idempotence

Toutes les erreurs ne se rejouent pas. Réessayer un 400 ou un 422 ne sert à rien ; réessayer un 429 ou un 503 est souvent la bonne réponse. Encore faut-il ne pas doubler l’effet.

Statuts à connaître

  • 200, 201, 204 : succès, création, succès sans contenu.
  • 400, 422 : requête ou données invalides. Corriger, ne pas rejouer.
  • 401, 403 : authentification ou droit. Vérifier le secret et le rôle.
  • 404, 409 : ressource absente, conflit (doublon).
  • 429 : trop de requêtes. Respecter Retry-After.
  • 500, 502, 503 : côté serveur. Retry avec backoff possible.

Retry propre

  • Backoff exponentiel avec un peu d’aléatoire, plafonné.
  • Un nombre maximal de tentatives, puis alerte et mise en file.
  • Jamais de retry sur une écriture sans clé d’idempotence.
  • Idempotency-Key : un identifiant unique par intention, réutilisé lors des tentatives.
  • Journaliser le statut, le corps d’erreur et l’identifiant de requête.

F. Webhooks et contrats d’API

Un webhook est une requête entrante non sollicitée : traitez-la comme une entrée utilisateur, pas comme une vérité. Vérifiez la signature, l’horodatage et la forme du payload avant d’agir.

Vérifier un webhook

  • Calculer le HMAC du corps brut avec le secret partagé.
  • Comparer en temps constant, pas avec ==.
  • Refuser un horodatage trop ancien pour limiter le rejeu.
  • Répondre 2xx vite, puis traiter en file : un webhook lent se fait réessayer.
  • Ne jamais faire confiance à un payload non signé, même s’il vient d’une IP connue.

Lire un contrat OpenAPI

  • Chercher servers, security et les schémas de requête.
  • Repérer les paramètres obligatoires et les formats de date.
  • Regarder les réponses d’erreur documentées, pas seulement le 200.
  • Un fichier OpenAPI permet de générer un client et des tests, au lieu de deviner.
Une intégration tient si elle échoue proprement : message clair, données conservées, reprise possible. Un workflow qui ne sait pas échouer finit par perdre des données sans que personne ne le remarque.