[:fr]La parole est aux speakers : Aurélien David[:]

[:fr]Jusqu’au Forum PHP 2018, retrouvez nos interviews de speakers pour mieux comprendre leur parcours et le sujet qu’ils aborderont lors de leur conférence !

La conférence

Tu nous parleras d’API GraphQL lors du Forum PHP 2018. Depuis combien de temps avez-vous cette API en production et quelle est l’envergure du projet ?

Avec mon équipe, on a commencé par tester GraphQL en janvier 2016, avec un simple PoC pour exporter des données dans un fichier CSV directement depuis une requête GraphQL… Après avoir expérimenté avec les deux implémentations en PHP youshido-php/GraphQL et webonyx/graphql-php, on a rapidement été convaincu des bénéfices. Nous avons finalement opté pour le bundle Symfony overblog/GraphQLBundle qui se base sur la seconde implémentation. Aujourd’hui cette API GraphQL est consommée par notre frontend en production et permet à toutes les plateformes de Cap Collectif de fonctionner. Que de chemin parcouru !

Depuis plusieurs de nos clients ont envie d’utiliser notre API pour réaliser des intégrations, telles que :

– L’affichage en temps réel du nombre de participants à une consultation;
– Synchroniser l’application d’agenda de la ville avec notre module d’agenda;
– etc…

Il était grand temps pour nous de documenter et d’ouvrir l’accès à ces données ! Ma conférence va traiter des problématiques liées à la sortie de notre API GraphQL publique.

Qu’est-ce qui vous a poussés à créer une API GraphQL, par rapport à une API REST plus classique ?

On a longtemps utilisé une API REST, depuis les débuts de Cap Collectif en fait ! Ce qui nous a donné envie de tester GraphQL c’est notre participation à GraphQL Future lors de React Europe en 2016; ils ont présenté sur scène tout ce dont nous rêvions d’avoir côté frontend.

Le PoC que j’évoquais plus haut nous a également séduits côté backend. En une semaine seulement, on avait reproduit une bonne partie des fonctionnalités de l’API REST pour notre application de consultation ! Fini de penser en terme d’endpoints, en verbes HTTP, en groupes de sérialisation pour éviter l’over-fetching… L’organisation autour d’un schéma nous permet de nous concentrer sur les `types`, `resolvers` et `mutations`. Ce changement de modèle a permis un réel gain de productivité au sein de l’équipe.

Pour être honnête ce n’est pas tout, on avait aussi très envie de tester Relay. On l’a mis en place dès la sortie de la version 2 (Relay Modern). Encore une fois on remplaçait une partie importante de notre code frontend qui était dédié à la récupération des données : l’appel des différents endpoints de l’API REST.

Bien sûr on était tout à fait conscient des nouveaux problèmes que GraphQL allait nous poser, j’en évoquais d’ailleurs déjà plusieurs au PHPTour de Nantes en 2017. Par exemple :

– Le cache réseau difficilement applicable, on doit compter sur du cache côté applicatif;
– La sécurité des entrées utilisateurs (complexité des requêtes, vérification des arguments…);
– Le monitoring qui ne concerne qu’un seul endpoint.

Mais au moment où on faisait ce choix, GitHub avait déjà annoncé la sortie de la version 4 de son API publique en GraphQL. Alors on s’est dit, pourquoi pas nous ? A partir de ce moment là, on a décidé de déprécier progressivement l’API REST. Dans un premier temps toutes les nouvelles fonctionnalités seraient développées en GraphQL. Puis petit à petit on migrerait les fonctionnalités existantes pour couvrir 100% de l’ancien périmètre.

Aujourd’hui on a totalement déprécié notre ancienne API. Même si, je dois l’avouer, tous les inconvénients de GraphQL n’ont pas encore été complètement résolus ! On reste plutôt confiant :
– L’utilisation progressive de `DataLoader` nous impose une rigueur dans la mise en place du cache et du traitement par lots (batching);
– Les promesses de la solution de monitoring Apollo Engine sont très prometteuses.

Si vous hésitez encore entre REST et GraphQL, je dirais que chez nous c’est vraiment l’attrait d’un code frontend simplifié qui nous a convaincus. D’ailleurs j’ai bien peur que dans quelques années les développeurs frontend refusent de travailler avec une API autre que GraphQL !

As-tu des bonnes pratiques en termes de documentation d’API GraphQL et plus particulièrement par rapport au versioning de celle-ci ?

La question de la documentation et du versioning n’est pas simple et on s’est beaucoup inspiré de ce qui se fait dans les quelques APIs GraphQL publiques : Github, Yelp, Shopify, …

On y retrouve de nombreuses bonnes pratiques ! La plus importante vis à vis du versioning c’est de quitter le schéma v1, v2, v3, … qui impose de grosses migrations aux clients et une maintenance importante pour le fournisseur de l’API. Je recommande d’opter pour une API évolutive ! D’ailleurs ce concept n’a rien à voir avec GraphQL; on peut très bien l’adopter en REST. Mais l’approche d’une API organisée autour d’un schéma que propose GraphQL, la rend plutôt intuitive. Attention, c’est aussi une contrainte qui nous impose de beaucoup travailler la conception du schéma, afin d’éviter au maximum les changements bloquants.

Je ne vais pas tout détailler dès maintenant, mais j’évoquerai notamment durant la conférence : différentes conventions de conception d’un schéma GraphQL, le choix d’une politique de dépréciations (avec la gestion des BCs), pourquoi est-ce qu’on a choisi d’utiliser plusieurs schémas en interne puis comment générer automatiquement la documentation et le changelog de l’API.

Une conférence présentée par

Aurélien DAVID

Rockstar dans l'âme, Aurélien aime autant réaliser des projets qui touchent la vie des gens, que des lignes de basses funky. JoliCodeur pendant 3 ans, il a toujours accordé beaucoup d'importance à la satisfaction des utilisateurs autant que des développeurs. Il accompagne désormais la startup Cap Collectif en tant que CTO, pour réaliser les meilleurs processus participatifs possible.

Autres interviews

[:]