Erreurs de configuration d'une REST API : exemples pratiques

Intro

Cette version française explique REST API configuration mistakes with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

La configuration peut faire ou défaire une REST API. De petits écarts sur CORS, les timeouts, la taille de requête, l'authentification ou les pools de connexions peuvent provoquer des pannes intermittentes difficiles à diagnostiquer. Ce guide propose des erreurs fréquentes réellement rencontrées, des étapes de REST API validation, des pratiques de REST API rollback et des workflows de REST API troubleshooting. Les exemples s'appuient sur Express (Node.js), MongoDB et des intégrations comme Stripe et l'OpenAI API.

Pour qui :

• Développeurs qui font grandir une API Express ou Node.js
• Consultants DevOps qui harmonisent des configs d'API
• Équipes startup qui intègrent des services tiers sous contrainte de temps

Ce que vous obtenez :

• Une checklist d'erreurs de REST API configuration
• Des exemples concrets de code et de config
• Un workflow de changement sécurisé, un petit plan pilote et une habitude de rollback

---

Erreurs de configuration courantes avec exemples pratiques

Voici des écueils observés en production, avec leurs correctifs applicables tout de suite.

1) CORS : valeurs par défaut permissives ou allowlists incohérentes

Symptôme :

• Tout marche en local mais les navigateurs échouent avec des erreurs CORS opaques.

Mauvais :

// Express
const cors = require('cors');
app.use(cors()); // Autorise toute origine, masque des bugs et ajoute du risque

Mieux (allowlist et méthodes explicites) :

const cors = require('cors');
const allowed = [
  'https://app.example.com',
  'https://admin.example.com'
];
app.use(cors({
  origin: (origin, cb) => {
    if (!origin || allowed.includes(origin)) return cb(null, true);
    return cb(new Error('Not allowed by CORS'));
  },
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  credentials: true
}));

Validation :

• Vérifiez le preflight : curl -i -X OPTIONS https://api.example.com/v1/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: GET"
• Confirmez que les origines non autorisées reçoivent 403 ou une erreur claire.

Rollback :

• Conservez l'ancienne config CORS en VCS ; revenez en arrière si les flux d'auth se brisent.

2) Limites du body parser : trop large ou trop strict

Symptôme :

• Les utilisateurs voient des 413 (payload trop gros) ou des requêtes qui bloquent.

Correctif :

const express = require('express');
const app = express();
app.use(express.json({ limit: '1mb' }));
app.use(express.urlencoded({ extended: false, limit: '1mb' }));

Astuce :

• Alignez les limites du reverse proxy (client body size) avec celles d'Express.

Validation :

• Envoyez un payload juste sous la limite puis juste au-dessus ; attendez 200 vs 413.

Rollback :

• Restaurez la limite précédente et redémarrez uniquement le groupe d'instances concerné.

3) Timeouts : client, serveur et proxy en décalage

Symptômes :

• Erreurs 499/504/408 aléatoires, retries webhook Stripe, ou abandons côté client.

Côté serveur (Node 18+) :

const server = app.listen(process.env.PORT || 3000);
server.requestTimeout = 60000;     // 60s pour le cycle complet de requête
server.headersTimeout = 65000;     // 65s pour éviter la course sur les en-têtes

Reverse proxy (exemple générique) :

# Alignez les timeouts du proxy et de l'app (valeurs d'exemple)
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Appels tiers :

• Fixez aussi des timeouts côté client sortant pour éviter qu'une API amont lente ne bloque votre service.

Validation :

• Simulez des handlers lents et vérifiez un timeout contrôlé et cohérent.

Rollback :

• Restaurez les valeurs précédentes et redéployez uniquement la config (pas le code).

4) Rate limiting : absent, incohérent ou trop strict

Symptômes :

• Quelques bursts et les utilisateurs reçoivent des 429 ; ou votre API reste ouverte aux abus.

Correctif Express :

const rateLimit = require('express-rate-limit');
app.use('/v1/', rateLimit({
  windowMs: 60 * 1000,
  max: 120,
  standardHeaders: true,
  legacyHeaders: false
}));

Validation :

• Envoyez 130 requêtes en 60s depuis une même IP ; 120 passent, 10 reviennent en 429.

Rollback :

• Augmentez la limite/la fenêtre ou retirez le middleware si des flux critiques cassent.

5) Auth et secrets : mauvaises clés d'env ou validations manquantes

Symptômes :

• Échecs de paiements, vérification webhook invalide, appels IA en 401.

Garde-fous pour Stripe et OpenAI :

if (process.env.NODE_ENV === 'production') {
  if (process.env.STRIPE_SECRET_KEY?.startsWith('sk_test_')) {
    throw new Error('Refusing to start with Stripe test key in production');
  }
}
if (!process.env.OPENAI_API_KEY) {
  throw new Error('OPENAI_API_KEY is required');
}

Vérification de signature (Stripe) :

// Conservez le corps brut pour vérifier la signature
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  try {
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
    // handle event
    res.sendStatus(200);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

Validation :

• Utilisez des événements de test connus et vérifiez la réussite et l'échec attendus.

Rollback :

• Gardez l'ancien secret et endpoint actifs jusqu'à confirmation du trafic.

6) Express derrière un proxy : trust manquant et cookies secure cassés

Symptômes :

• Les sessions ne tiennent pas ; Set-Cookie avec Secure ignoré.

Correctif :

app.set('trust proxy', 1); // s'il y a exactement un reverse proxy
// ou app.set('trust proxy', true) pour plusieurs proxies

Puis des cookies sécurisés :

app.use(require('cookie-session')({
  name: 'sid',
  secret: process.env.SESSION_SECRET,
  cookie: { secure: true, sameSite: 'lax', httpOnly: true }
}));

Validation :

• Confirmez que le proxy envoie X-Forwarded-Proto: https et qu'Express le respecte.

Rollback :

• Restaurez la valeur précédente de trust proxy si le comportement régresse.

7) Problèmes de connexion MongoDB et dimensionnement des pools

Symptômes :

• Latence en pics, timeouts pendant les bursts, tempêtes de connexions au déploiement.

Connexion (exemple) :

const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.MONGODB_URI, {
  maxPoolSize: 20,
  minPoolSize: 5,
  serverSelectionTimeoutMS: 5000,
  retryWrites: true
});

Bonnes pratiques :

• Un client par processus et réutilisation des connexions.
• Des pools raisonnables ; trop grands, ils saturent le serveur.
• Vérifiez les index pour les requêtes chaudes ; un index manquant ressemble à un bug applicatif.

Validation :

• Chargez avec trafic en rafales, observez l'utilisation des connexions et la latence.

Rollback :

• Revenez aux tailles précédentes ; redémarrez d'abord une seule instance pour observer.

8) Pagination par défaut et taille de réponse

Symptômes :

• Les clients tirent trop de données par défaut ; latence et mémoire augmentent.

Correctif :

const DEFAULT_PAGE_SIZE = 50;
const MAX_PAGE_SIZE = 200;

app.get('/v1/items', async (req, res) => {
  const page = Math.max(1, parseInt(req.query.page || '1', 10));
  const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, parseInt(req.query.pageSize || DEFAULT_PAGE_SIZE, 10)));
  // query avec limit/skip selon page et pageSize
});

Validation :

• Incluez total, page et pageSize pour aider les clients à s'adapter.

Rollback :

• Si des clients cassent, rétablissez l'ancien défaut et planifiez une migration.

9) Journalisation et rédaction

Symptômes :

• Soit aucune donnée exploitable, soit des fuites d'informations sensibles.

Correctif :

• Fixez LOG_LEVEL=info en production et assurez-vous de la rédaction des tokens.
• Échantillonnez les logs de debug uniquement sur des endpoints ciblés pendant un incident.

Validation :

• Vérifiez la rédaction d'en-têtes sensibles (Authorization).

Rollback :

• Baissez la verbosité si le logging sature le stockage ou gonfle les coûts.

---

Workflow global

Adoptez un flux simple et répétable pour vos changements de configuration.

1. Baseline et diff

• Capturez la config et les valeurs runtime (timeouts, limites, clés présentes, en-têtes proxy).
• Définissez le changement minimal et sa raison.

1. Changer en un seul endroit

• Modifiez un seul contrôle à la fois (ex. allowlist CORS sur une route).
• Si possible, placez-le derrière un flag ou un middleware spécifique à la route.

1. Valider avec des checks répétables

• Fonctionnel : codes de statut, tailles de payload, preflight CORS, parcours auth.
• Non-fonctionnel : latence, taux d'erreurs, mémoire, connexions ouvertes.
• Intégrations : test Stripe, petite complétion OpenAI, lecture/écriture MongoDB.

1. Déployer en étapes

• Commencez par une instance ou un environnement.
• Surveillez métriques et logs avant d'étendre.

1. Observer et décider

• Fixez des seuils de succès/rollback à l'avance (ex. 99,9 % succès, p95 < 300 ms, 429 < 1 %).

1. Roll back rapide

• Restaurez les commits de config ou basculez un flag.
• Annoncez le résultat et planifiez un correctif plus profond si nécessaire.

---

Plan pilote local

Objectif : livrer une amélioration mesurable et étroite, vérifiable sur un poste avant un déploiement large.

Exemple de pilote : resserrer la taille de corps et ajouter une allowlist CORS sur une ressource.

Périmètre

• Route : POST /v1/uploads
• Changements : express.json({ limit: '1mb' }), allowlist des origines pour l'UI d'upload
• Métriques : taux 2xx, distribution 4xx (surtout 413 et 403), p95, tailles de payload

Étapes

1. Préparer

• Ajoutez une config avec défauts sensés et overrides via env.
• Ajoutez métriques ou logs pour observer la taille et l'origine des requêtes.

1. Tester en poste

• Tailles de payload :
• curl -s -o /dev/null -w "%{http_code}\n" -H "Content-Type: application/json" --data @payload-900kb.json https://api.example.com/v1/uploads
• Attendu : 200
• Refaire avec payload-1100kb.json, attendu : 413
• Preflight CORS :
• curl -i -X OPTIONS https://api.example.com/v1/uploads -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

1. Déploiement progressif

• Activez uniquement sur POST /v1/uploads.
• Observez 30-60 min ; comparez avant/après.

1. Décision

• Si les métriques tiennent et les erreurs n'augmentent pas, étendez aux routes sœurs.
• Sinon, rollback et analysez les logs pour clients/proxy mal alignés.

Rollback

• Revenez sur la change list ; confirmez le retour au comportement précédent en quelques minutes.
• Documentez le problème et les clients affectés.

---

Workflows de dépannage

Quand un problème survient après une modification de config, suivez ces chemins rapides.

1. Confirmer le symptôme

• Endpoint, méthode, code de statut, plage temporelle exacts.

1. Reproduire avec en-têtes

• curl -v -H "Origin: https://app.example.com" -H "Accept: application/json" -H "Content-Type: application/json" https://api.example.com/v1/items
• Inspectez les en-têtes de réponse (CORS, cache, content-type) et les timings.

1. Vérifier logs et métriques

• Repérez des pics de 4xx/5xx, 429, timeouts, mémoire ou saturation des pools.

1. Inspecter les frontières

• Limites et timeouts du reverse proxy vs ceux de l'app.
• Terminaison TLS et en-têtes X-Forwarded-*.

1. Valider les hypothèses tierces

• Stripe : type de clé adapté à l'environnement ; signature webhook vérifiée.
• OpenAI : clé présente ; tailles et timeouts conformes à vos limites.

1. Connectivité base de données

• Pool size, serverSelectionTimeout et authentification dans la chaîne de connexion.

1. Rollback en dernier recours

• Préférez un flag de config ou un revert d'un seul commit plutôt qu'un hotfix.

---

Conclusion

Des changements petits et explicites valent mieux que des retouches larges et risquées. Utilisez des allowlists CORS, fixez des limites raisonnables (taille de corps, timeouts), dimensionnez correctement vos pools et protégez vos secrets. Validez avec des checks répétables, déployez par étapes et gardez un chemin de rollback simple et rapide. Démarrez par un pilote étroit, mesurez les effets réels, puis étendez en confiance. Cela réduit les REST API config mistakes et améliore durablement la stabilité de votre service.