AFUP AFUP Day 2019 Baromètre Planète PHP

La parole est aux speakers : Aurélien David

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

Maintenir et faire évoluer une API GraphQL

Comment éviter de casser une API pour ses clients ? Comment continuer de la faire évoluer, le tout sans subir une maintenance trop lourde ? La solution n'est pas simple… Reprenons les bases : l'évolution d'une API consiste à s'efforcer de maintenir le corps de la requête / réponse, les paramètres de la requête, ses fonctionnalités générales, en ne les brisant que lorsque cela est absolument nécessaire. Ce concept n'est pas nouveau, mais il faut le dire, GraphQL va bien nous faciliter la tâche. Voyons ensemble comment mettre en place une API GraphQL évolutive, nous apportant plus de flexibilité et de liberté, tout en évitant (en théorie) aux clients d'avoir à migrer leur application vers une nouvelle version complètement différente.

Katherine Johnson
25/10/2018
11:25-12:05

Le speaker

Aurélien David
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.

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.

La conférence

Maintenir et faire évoluer une API GraphQL

Comment éviter de casser une API pour ses clients ? Comment continuer de la faire évoluer, le tout sans subir une maintenance trop lourde ? La solution n'est pas simple… Reprenons les bases : l'évolution d'une API consiste à s'efforcer de maintenir le corps de la requête / réponse, les paramètres de la requête, ses fonctionnalités générales, en ne les brisant que lorsque cela est absolument nécessaire. Ce concept n'est pas nouveau, mais il faut le dire, GraphQL va bien nous faciliter la tâche. Voyons ensemble comment mettre en place une API GraphQL évolutive, nous apportant plus de flexibilité et de liberté, tout en évitant (en théorie) aux clients d'avoir à migrer leur application vers une nouvelle version complètement différente.

Katherine Johnson
25/10/2018
11:25-12:05

Le speaker

Aurélien David
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

En poursuivant votre navigation sur ce site, vous acceptez l’utilisation des cookies pour améliorer votre navigation. plus d'infos

1. Qu’est-ce qu’un cookie?

Un Cookie est un petit fichier texte enregistré sur votre terminal (ordinateur, tablette, smartphone, etc.), à l’occasion de la consultation d’un service en ligne grâce à votre logiciel de navigation. Il permet à son émetteur d’identifier le terminal dans lequel il est enregistré, pendant la durée de validité ou d’enregistrement du Cookie. Lors de la consultation de notre site Internet, des informations relatives à la navigation de votre terminal sont susceptibles d'être enregistrées dans ces fichiers dits "Cookies". Ces derniers sont installés sur votre terminal, sous réserve des choix que vous auriez exprimés concernant les Cookies et que vous pouvez modifier à tout moment.

2. A quoi servent les cookies émis sur notre site ?

Seul l’émetteur d’un cookie est susceptible de lire ou de modifier les informations qui y sont contenues.
Les cookies utilisés sur notre site permettent :

3. Vos choix concernant les cookies

Vous disposez de différents moyens pour gérer les cookies. Tout paramétrage que vous pouvez entreprendre sera susceptible de modifier votre navigation sur notre site et sur Internet en général et vos conditions d'accès à certains services de notre site nécessitant l'utilisation de cookies. Vous pouvez à tout moment exprimer et modifier vos souhaits en matière de cookies, par les moyens décrits ci-dessous. L'accord sur les cookies L'enregistrement d'un cookie dans un terminal est essentiellement subordonné à la volonté de l'utilisateur du terminal, que celui-ci peut exprimer et modifier à tout moment et gratuitement à travers les choix qui lui sont offerts par son logiciel de navigation. Si vous avez accepté dans votre logiciel de navigation l'enregistrement de cookies dans votre terminal, les cookies intégrés dans les pages et contenus que vous avez consultés pourront être stockés temporairement dans un espace dédié de votre terminal. Ils y seront lisibles uniquement par leur émetteur.

Le refus des cookies Si vous refusez l'enregistrement de cookies dans votre terminal, ou si vous supprimez ceux qui y sont enregistrés, vous ne pourrez plus bénéficier d'un certain nombre de fonctionnalités qui sont néanmoins nécessaires pour naviguer dans certains espaces de notre site. Tel serait le cas si vous tentiez d'accéder à votre compte ou à votre abonnement qui nécessite de vous identifier. Tel serait également le cas lorsque nous, ou nos prestataires, ne pourrions pas reconnaître, à des fins de compatibilité technique, le type de navigateur utilisé par votre terminal, ses paramètres de langue et d'affichage ou le pays depuis lequel votre terminal semble connecté à Internet. Le cas échéant, nous déclinons toute responsabilité pour les conséquences liées au fonctionnement dégradé de nos services résultant de l'impossibilité pour nous d'enregistrer ou de consulter les cookies nécessaires à leur fonctionnement et que vous auriez refusés ou supprimés. Les choix offerts par votre logiciel de navigation Vous pouvez configurer votre logiciel de navigation de manière à ce que des cookies soient enregistrés dans votre terminal ou, au contraire, qu'ils soient rejetés, soit systématiquement, soit selon leur émetteur. Vous pouvez également configurer votre logiciel de navigation de manière à ce que l'acceptation ou le refus des cookies vous soient proposés ponctuellement, avant qu'un cookie soit susceptible d'être enregistré dans votre terminal. Pour la gestion des cookies et de vos choix, la configuration de chaque navigateur est différente. Elle est décrite dans le menu d'aide de votre navigateur, qui vous permettra de savoir de quelle manière modifier vos souhaits en matière de cookies. Selon votre navigateur, consultez le lien ci-dessous pour configurer votre navigateur et refuser les cookies :