Après des années à construire et auditer des APIs, certaines erreurs reviennent avec une régularité frappante. Ce ne sont pas des oublis de syntaxe,ce sont des choix architecturaux qui semblent raisonnables au départ mais deviennent douloureux à l'échelle.

1. Exposer le schéma de base de données directement

Retourner des lignes brutes de base de données depuis l'API couple les clients au schéma interne. Toute migration,renommer une colonne, diviser une table,devient un changement cassant de l'API. Toujours utiliser une couche de sérialisation (API Resources, DTOs) entre les données et la réponse.

2. Pas de versioning

Livrer une API publique ou semi-publique sans versioning signifie que chaque changement cassant est une crise. Ajouter `/v1/` aux routes dès le premier jour. Ça ne coûte presque rien et économise des douleurs enormes quand on doit faire évoluer le contrat.

3. Réponses d'erreur incohérentes

// Mauvais : chaque endpoint a son propre format d'erreur
{ "msg": "not found" }
{ "error_code": 404, "message": "L'utilisateur n'existe pas" }
{ "errors": ["Ressource non trouvée"] }

// Bien : format RFC 7807 cohérent
{
  "type": "https://api.exemple.com/errors/not-found",
  "title": "Ressource Non Trouvée",
  "status": 404,
  "detail": "L'utilisateur avec l'id 42 n'existe pas."
}

4. Bloquer le cycle de requête avec des tâches lourdes

Génération de rapports, envoi d'emails, création de PDF,ces opérations ne doivent jamais bloquer une réponse HTTP. Les pousser dans une queue, retourner un job ID immédiatement, et laisser le client interroger ou recevoir un webhook quand la tâche est terminée.

5. Pas de pagination sur les endpoints de liste

• ✓Idempotence manquante sur les endpoints POST (requêtes dupliquées = données dupliquées)
• ✓Pas de rate limiting sur les endpoints publics (vulnérabilité DoS)
• ✓Secrets dans les paramètres de requête plutôt que dans les headers (les logs les exposent)
• ✓Pas de documentation API,OpenAPI/Swagger prend quelques minutes à configurer