# Migration vers Huma v2 avec parité de 100 %

Migré l'API HTTP de Fiber vers Huma v2 — 649 chemins et 760 opérations — puis atteint et maintenu une correspondance de 100 % entre les routes enregistrées par le serveur et la description OpenAPI publiée.

2025

**Situation.** L'API a commencé sur Fiber, avec une validation des requêtes écrite à la main, point de terminaison par point de terminaison. Cela convient lorsqu'il n'y en a qu'une poignée. Ce n'est plus le cas lorsque le périmètre grandit : cette validation artisanale devient une charge de maintenance, et de petites incohérences apparaissent, car les contrôles de chaque point de terminaison constituent leur propre cas particulier. Il n'existait par ailleurs aucune description unique de la structure de l'API.

**Tâche.** L'objectif était que la validation découle des types plutôt que de contrôles écrits à la main, avec un véritable contrat décrivant l'API — sans s'arrêter pour une réécriture globale d'un seul coup.

**Action.** La couche HTTP est passée à Huma v2 au‑dessus de Fiber, conservant ainsi le moteur d'exécution existant. Chaque point de terminaison reçoit des structures d'entrée et de sortie, à partir desquelles Huma génère la validation des requêtes et la modélisation des réponses. Une description OpenAPI en découle sans travail supplémentaire, ce qui permet à la documentation de suivre le code au lieu de dépérir dans un wiki. Tout nouvel élément a été écrit avec Huma et les routes existantes migrées, avec exactement deux points de terminaison restant directement sur Fiber — ceux des WebSocket, où l'accès au socket est réellement nécessaire et où le modèle requête/réponse de Huma ne convient pas. L'ensemble a atteint 649 chemins portant 760 opérations, avec un contrôle en CI comparant les routes réellement enregistrées par le serveur à celles annoncées dans la description OpenAPI. La correspondance est de 100 % et le reste, car une route non décrite fait échouer la compilation.

**Résultat.** Les nouveaux points de terminaison bénéficient d'une validation et d'une documentation à jour sans travail supplémentaire, et toute une catégorie de défauts de traitement des requêtes — du type « oh, ce champ n'a pas été vérifié ici » — a disparu. Avec 760 opérations, la description est le seul moyen pratique de consulter l'API, si bien que la garantie de son exhaustivité compte davantage qu'à cinquante. Le contrat typé a rendu l'API plus sûre à modifier et plus facile à transmettre, car les types indiquent ce qu'attend un point de terminaison.

---

- Rôle: Ingénieure backend
- Catégories: [Architecture de plateformes](https://engineer.company/fr/categories/platform-architecture/), [Ingénierie backend](https://engineer.company/fr/categories/backend/), [API et intégration](https://engineer.company/fr/categories/api/), [Migrations et modernisation](https://engineer.company/fr/categories/migration/), [Tests et assurance qualité](https://engineer.company/fr/categories/testing/), [Documentation](https://engineer.company/fr/categories/documentation/)
- Prestations: [Architecture de plateformes et de solutions](https://engineer.company/fr/services/platform-architecture/), [Développement backend et API](https://engineer.company/fr/services/backend-development/), [Outils pour agents d'IA et serveurs MCP](https://engineer.company/fr/services/ai-tools/), [Documentation technique](https://engineer.company/fr/services/technical-documentation/)

<https://engineer.company/fr/portfolio/migrated-the-api-to-huma-v2-at-100-parity/>
