Le choix de l'architecture API arrive tôt dans un projet Symfony, souvent au moment où l'on sait encore peu de choses sur les clients qui vont la consommer. C'est précisément le mauvais moment pour trancher par réflexe. API Platform, contrôleurs REST écrits à la main ou GraphQL : les trois options sont solides, mais elles n'optimisent pas la même chose et n'imposent pas les mêmes contraintes sur les cinq années suivantes.
Ce comparatif expose ce que chaque approche coûte vraiment, à quel profil de projet elle convient et comment décider sans se tromper de critère.
Ce qu'une API métier doit tenir dans le temps
Avant de comparer les outils, il faut nommer ce qu'on attend d'une API dans une application métier qui vivra plusieurs années.
Elle doit exposer un contrat stable : les clients, qu'il s'agisse d'un front Vue.js, d'une application mobile ou d'un partenaire, ne doivent pas casser à chaque évolution interne. Elle doit être sécurisée avec précision, car les règles d'accès dans un ERP ou un CRM sont rarement binaires. Elle doit rester lisible pour l'équipe qui la reprendra, et testable sans acrobaties. Enfin elle doit permettre d'optimiser les points chauds sans réécrire le reste.
Ces quatre exigences, contrat, sécurité, lisibilité et performance ciblée, sont les seuls critères qui comptent. Le reste est affaire de goût.
REST custom : la maîtrise totale, au prix de la discipline
Écrire son API à la main avec Symfony, c'est utiliser les composants natifs du framework : un contrôleur par cas d'usage, des DTO en entrée et en sortie, le sérialiseur pour la transformation, le validateur pour les règles, les voters pour la sécurité. Rien n'est magique. Chaque endpoint fait exactement ce qu'on a écrit.
C'est l'approche qui laisse le plus de liberté sur la modélisation. Une API métier expose rarement des tables : elle expose des actions. « Valider une commande », « clôturer un dossier », « affecter un technicien » ne sont pas des opérations CRUD, et les forcer dans ce moule produit des API qui mentent sur ce qu'elles font. Avec des contrôleurs dédiés, chaque action métier a son endpoint, son DTO et sa logique, ce qui s'accorde naturellement avec une architecture Symfony propre où le domaine reste isolé de l'infrastructure.
Le prix, c'est la discipline. Sans conventions fortes, une API custom dérive vite : pagination gérée différemment selon les endpoints, formats d'erreur incohérents, documentation OpenAPI maintenue à la main puis abandonnée. Ce n'est pas une limite technique, c'est une limite d'équipe. Une équipe senior qui pose ses conventions dès le départ produit une API custom impeccable. Une équipe qui bricole produit un chantier.
REST custom convient quand l'API est le reflet d'un métier riche, avec peu de ressources mais beaucoup de règles, et qu'un développeur Symfony expérimenté tient l'architecture.
API Platform : la productivité par les conventions
API Platform part d'une hypothèse différente : une grande partie des API exposent des ressources aux comportements répétitifs, et automatiser ces comportements fait gagner un temps considérable. On annote une classe, et le framework génère les opérations, la pagination, les filtres, la validation, la documentation OpenAPI, le format d'erreur normalisé et même les formats JSON-LD ou Hydra.
Pour une API qui expose vingt ou trente ressources aux règles proches, c'est un gain de productivité réel et une garantie de cohérence que peu d'équipes tiennent à la main. La documentation est toujours à jour parce qu'elle est dérivée du code. Les clients front bénéficient de conventions prévisibles.
Les difficultés apparaissent dès que le métier sort du cadre. Les opérations qui ne sont pas du CRUD, les transitions d'état complexes, les règles de sécurité qui dépendent du contexte plutôt que de la ressource : tout cela se fait, mais via des mécanismes d'extension, des processeurs, des providers et des configurations dont la courbe d'apprentissage est sérieuse. Le risque classique est de voir la logique métier se disperser dans des annotations et des hooks du framework au lieu de vivre dans des services explicites. Quand cela arrive, l'application devient dépendante d'API Platform bien au-delà de la couche HTTP, et la reprise par une autre équipe se complique.
Une autre limite est plus subtile : API Platform pousse à exposer les entités Doctrine directement. C'est rapide, mais cela couple le contrat public au schéma de base de données. Un renommage de colonne devient une rupture de contrat. L'usage de DTO dédiés corrige le problème, mais il retire une partie de la magie qui justifiait le choix.
API Platform s'impose quand l'API est large, majoritairement orientée ressources, et que l'équipe accepte de travailler dans ses conventions plutôt que contre elles.
GraphQL : la flexibilité côté client, la complexité côté serveur
GraphQL renverse la logique : ce n'est plus le serveur qui décide de la forme des réponses, c'est le client qui décrit exactement les données dont il a besoin. Une seule requête peut remonter une commande, ses lignes, le client associé et l'historique des paiements, sans multiplier les appels.
Pour un front riche aux besoins variables, ou pour plusieurs clients aux écrans très différents, c'est un avantage net. L'équipe front avance sans attendre qu'on lui crée un endpoint spécialisé. Le schéma typé sert de contrat vivant et outillé.
La contrepartie se paie côté serveur. Chaque champ est résolu par une fonction, et sans mécanisme de batching, une requête un peu profonde déclenche le fameux problème N+1 sur la base de données. Le cache HTTP, qui rend une API REST scalable presque gratuitement, ne s'applique plus tel quel puisque toutes les requêtes passent par un même point d'entrée. La sécurité doit se penser au niveau du champ, pas de la route, et limiter la profondeur ou le coût des requêtes devient une obligation pour éviter qu'un client ne mette le serveur à genoux. Sur Symfony, l'intégration passe par des bibliothèques dédiées ou par le mode GraphQL d'API Platform, avec dans les deux cas une couche supplémentaire à maîtriser.
GraphQL convient quand la diversité des clients justifie sa flexibilité et que l'équipe backend est prête à assumer la charge d'optimisation et de sécurisation qu'il implique. Pour une API interne consommée par un seul back-office, c'est le plus souvent une complexité sans contrepartie.
Les critères qui tranchent réellement
Le choix se fait bien mieux en répondant à quatre questions qu'en comparant des listes de fonctionnalités.
Combien de ressources, et à quel point se ressemblent-elles ? Beaucoup de ressources homogènes plaident pour API Platform. Peu de ressources mais des actions métier riches plaident pour REST custom.
Combien de clients, et à quel point leurs besoins divergent-ils ? Un client unique ou des clients aux besoins proches ne justifient pas GraphQL. Plusieurs clients aux écrans très différents peuvent le justifier.
Où doit vivre la logique métier ? Si la réponse est « dans des services explicites, testables sans HTTP », les trois options fonctionnent, mais REST custom rend cette isolation naturelle alors qu'API Platform et GraphQL demandent une vigilance active pour ne pas laisser la logique glisser dans les mécanismes du framework.
Qui maintiendra le code dans trois ans ? Une API custom bien documentée se reprend avec des compétences Symfony standard. Une API Platform fortement personnalisée ou un schéma GraphQL optimisé demandent des compétences spécifiques, plus rares.
Le tableau suivant résume les forces de chaque option sur les quatre exigences posées en introduction.
| REST custom | API Platform | GraphQL | |
|---|---|---|---|
| Stabilité du contrat | Forte avec des DTO | Fragile si entités exposées, forte avec DTO | Forte grâce au schéma typé |
| Sécurité fine | Naturelle via voters | Possible, via configuration | À concevoir champ par champ |
| Lisibilité et reprise | Excellente si conventions posées | Bonne dans le cadre, difficile hors cadre | Demande des compétences spécifiques |
| Performance ciblée | Simple, cache HTTP natif | Simple pour le CRUD, plus fine sur le sur-mesure | Complexe, batching et limitation obligatoires |
Le piège le plus fréquent : choisir avant d'avoir modélisé
La plupart des mauvais choix d'architecture API viennent d'un choix pris avant d'avoir compris le métier. On installe API Platform parce que c'est l'outil du moment, on découvre trois mois plus tard que soixante pour cent des opérations sont des transitions d'état qui ne rentrent pas dans le CRUD, et on passe le reste du projet à contourner l'outil. Ou l'on adopte GraphQL pour un back-office unique, et l'on hérite d'un serveur difficile à cacher et à sécuriser sans en tirer le moindre bénéfice.
La séquence saine est inverse. On modélise d'abord le domaine : quelles entités, quelles actions, quelles règles d'accès, quels clients. On identifie ensuite le ratio entre opérations CRUD et opérations métier, et la diversité réelle des consommateurs. L'architecture API découle de cette analyse au lieu de la précéder. C'est exactement le travail que nous faisons en amont d'un développement d'ERP ou de CRM sur-mesure, et c'est aussi ce qu'un audit technique remet à plat sur une API existante qui a dérivé.
Comment on tranche chez Kérynox
Pour une application métier au domaine riche, notre préférence va à une API REST structurée à la main, avec des DTO explicites, une logique métier isolée dans des services de domaine et des conventions d'API fixées dès le premier endpoint. C'est l'approche qui vieillit le mieux et qui se reprend le plus facilement.
API Platform reste un excellent choix quand l'API est large et majoritairement orientée ressources, à condition de garder la logique métier hors des mécanismes du framework et d'exposer des DTO plutôt que des entités. GraphQL entre en jeu quand plusieurs clients aux besoins très différents consomment la même API et que l'équipe a les compétences pour en assumer la charge côté serveur.
Dans tous les cas, ce qui fait la qualité d'une API n'est pas l'outil mais la clarté du contrat, l'isolation du métier et la constance des conventions. Si vous hésitez sur l'architecture d'une API Symfony en projet ou si votre API actuelle est devenue difficile à faire évoluer, décrivez-nous votre contexte : nous vous dirons quelle approche tient dans la durée pour votre cas, sans vous vendre un outil par principe.