MODULE 17 / 72
🔧
C'est quoi une API propre (et pourquoi 90% sont mal conçues)
Une API est un contrat. Comme un contrat légal, on ne le modifie pas sans prévenir les parties. Et comme un mauvais contrat, une API mal conçue devient une source de bugs, de confusion, et de douleur pour tous ceux qui l'utilisent — y compris vous-même dans 6 mois.
REST propre : les règles de base. Les URLs désignent des ressources (noms), pas des actions (verbes). BON : `GET /orders/123`. MAUVAIS : `GET /getOrder?id=123`. Les verbes HTTP portent l'action : GET pour lire, POST pour créer, PATCH pour modifier partiellement, DELETE pour supprimer. Les codes de statut sont précis : 201 pour une création (pas 200), 204 pour une suppression sans contenu, 404 si la ressource n'existe pas, 409 en cas de conflit.
La pagination : obligatoire dès le premier jour. Jamais `GET /orders` qui renvoie toutes les commandes. Avec 100 000 lignes, votre app plante. Toujours paginer : `GET /orders?page=1&limit=20`. La réponse inclut `{ items: [...], total: 100000, page: 1, hasMore: true }`. Alternative moderne : la pagination par curseur — `GET /orders?after=cursor_xyz&limit=20`. Plus efficace sur les grandes tables car elle évite les OFFSET coûteux.
L'idempotence : la propriété qui sauve des vies. Une requête idempotente produit le même résultat qu'on l'exécute 1 ou 10 fois. GET, PUT, DELETE sont idempotents. POST ne l'est pas — chaque appel crée une nouvelle ressource. Problème réel : le réseau coupe pendant qu'un client passe une commande. Il réessaie. Vous avez maintenant deux commandes. Solution : un `idempotency_key` unique envoyé par le client. Si la clé existe déjà, on renvoie le résultat précédent sans ré-exécuter. Stripe l'implémente sur tous ses endpoints de paiement.
Le versioning : toujours, dès le début. Votre API en production est consommée par des clients. Si vous changez le format d'une réponse, vous cassez ces clients. Solution : versionner. `/api/v1/orders` reste stable. Si vous devez changer le format, vous créez `/api/v2/orders` et vous maintenez les deux pendant une période de transition. Dans Xano : utilisez des groupes d'API versionnés dès le premier endpoint. Changer plus tard coûte 10× plus cher.
Webhooks vs polling. Le webhook notifie en temps réel (push) — à privilégier en production. Le polling interroge à intervalles réguliers (pull) — simple à prototyper, coûteux à l'échelle. Le module 'Communications asynchrones' détaille les cas d'usage et les patterns Make/Stripe.
La gestion d'erreurs : un art souvent négligé. Une bonne gestion d'erreurs inclut : (1) Le bon code HTTP, (2) Un message humain lisible, (3) Un code d'erreur machine pour que le client puisse réagir différemment selon l'erreur, (4) Le request_id pour corréler avec les logs. Exemple parfait : `{ error: { code: 'INSUFFICIENT_STOCK', message: 'Le produit X n'est plus en stock', request_id: 'req_abc' } }`. Ce que les mauvaises APIs font : renvoyer `{ error: 'Something went wrong' }` avec un code 500 pour tout.
⚡ ANALOGIE — LE CONTRAT DE LOCATION D'UN APPARTEMENT
REST propre = un contrat clair, bien rédigé. Pagination = ne jamais envoyer tous les documents en vrac, les classer par lots numérotés. Idempotence = signer deux fois le même document ne crée pas deux contrats. Versioning = si on change les termes, on crée un avenant (v2) sans détruire l'original. Webhooks = le propriétaire vous appelle quand quelque chose change, au lieu que vous lui téléphoniez toutes les heures. Gestion d'erreurs = un refus clairement motivé avec les raisons précises, pas juste 'non'.
📐 SCHÉMA
GET/api/v1/orders?page=1&limit=20200 OK→ Paginé, versionné
POST/api/v1/orders201 Created→ Idempotency-Key header
PATCH/api/v1/orders/uuid200 OK→ UUID, pas d'ID séquentiel
DELETE/api/v1/orders/uuid204 No Content→ Idempotent
💬 QUESTION INTERACTIVE
1/5
"Dans Xano, comment concevoir vos API paths pour qu'ils soient propres et maintenables ?"
🎯 PIÈGE / QUESTION D'ENTRETIEN
Quelle est la différence entre PUT et PATCH ?