Comprendre les API
Lire, tester et gérer les erreurs
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
Authorization: Bearer sk_test_4eC39H...
Content-Type: application/x-www-form-urlencoded
amount=2000¤cy=eur&automatic_payment_methods[enabled]=true
GET (Lire), POST (Écrire),
PUT/PATCH (Modifier), DELETE (Supprimer).
L’adresse du guichet unique.
Les métadonnées (Auth, Format). Le "sticker sur l’enveloppe".
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
codecontreAccess Token(valide 1h). - 4. Utilise
Refresh Tokenpour renouveler.
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 (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.
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.
-H "Authorization: Bearer 123" \
-H "Content-Type: application/json" \
-d '{"name":"Bob"}'
-X POST-> Méthode-H "..."-> Header-d '...'-> Body (Data)
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=1ouper_page=1avant 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.
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
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,securityet 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.