Symfony Online 2023 : Design your API for the future

Cette 5^è édition, autour de l’écosystème Symfony, a regroupé plusieurs acteurs présentant les actualités du framework Symfony, des retours d’expériences, etc. Durant ces 2 jours, l'une des conférences m’a particulièrement intéressé, et j’aimerais vous la partager dans cet article.

Le thème traité : les API, un sujet qui concerne la grande majorité des développeurs. Et plus précisément : « Comment les garder maintenable dans le temps malgré les nouvelles versions de celles-ci ».

Titouan Galopin, membre de la Core Team Symfony, a présenté cette conférence, et voici les trois points que je vous invite à respecter afin d’avoir une API qui garantisse un bon confort d’utilisation :

• Rester stable dans le temps ;
• Gérer plusieurs versions ;
• Communiquer les changements aux utilisateurs.

Premier point : Rester stable dans le temps

Avant de développer une API, il faut avoir en tête qu’il s’agit ni plus ni moins que d'un “contrat”. D’autres développeurs qui vont l’utiliser vont se baser sur celui-ci et partir du principe que la donnée qu’ils reçoivent et envoient depuis leur application est celle convenue. Il est donc important de respecter certaines règles afin de se faciliter la tâche et de garantir une consistance du format de données.

Une solution à cela, qui nous permet de prendre un minimum de risques, est le découplage de la donnée interne et externe. Un peu à l’image d’une librairie PHP qui aurait ses méthodes internes pour faire son traitement et des méthodes externes que l’utilisateur peut manipuler. Ici, la donnée interne est celle que nous traitons au sein de notre API, alors que la donnée externe est celle exposée dans notre API. En d’autres termes, nous ne voulons pas exposer directement nos entités sérialisées. Nous passerons plutôt par un “transformer”, qui aura la charge de convertir notre entité en une structure prête à être exposée.

Ainsi, même si des changements ont lieu au sein de l’entité, la donnée exposée reste inchangée.

Nous avons donc vu la marche à suivre pour une donnée exposée, mais qu’en est-il des données d’entrée, lorsque l’utilisateur veut nous les envoyer ? Dans ce cas une solution est les DTO (Data Transfer Object). Ils permettent de contenir notre donnée, tout en s’assurant de respecter une certaine structure et certains types de données.

Ainsi on pourra désérialiser la donnée utilisateur dans cet objet pour la stocker et la valider au passage. Le faire directement dans l’entité comporterait des risques dans le cas où elle changerait, ce qui créerait des problèmes de compatibilité.

Deuxième point : Gérer plusieurs versions

Si vous avez besoin de faire des “breaking changes”, il vous faudra monter en version majeure de notre API (pour en savoir plus, je vous conseille cet article). Cette méthode permettra aux utilisateurs utilisant une version antérieure de ne pas rencontrer de mauvaises surprises. Il faudra donc maintenir plusieurs versions.

La solution évoquée au point précédent va une fois de plus nous aider. Rappelez-vous, nous avons découpé la donnée interne de l'externe, on pourra donc avoir une donnée externe par version, et d’un point de vue technique, des DTO et Transformer propre à chaque version. Il vous faudra également créer des routes pour chacune d’elles, pour qu’elles soient toutes exposées à l’utilisateur.

Dernier point : Communiquer les changements

Il est également important, lorsque vous apportez des modifications à votre API, de les documenter (nouveaux champs, nouvelles routes, etc.), ainsi que d’informer sur les dépréciations, d’autant plus lors de montées de versions majeures.

Vous pouvez par exemple utiliser OpenAPI, qui est prévu à cet effet. Ainsi l’utilisateur pourra accéder à la documentation de la version qu’il utilise et mettre à jour ses appels à l’API au fil du temps.

Il existe de nombreux outils autour de ce format qui vous permettront d’avoir une documentation efficace. Sur OpenAPI.Tools, vous trouverez certainement l'outil qui vous correspond.

Maintenant, vous en savez plus sur cette conférence. J’espère que cet article vous a convaincu qu’en découpant certaines parties de notre API, il était plus aisé de gérer ses différentes versions, mais également qu’il était important de documenter les évolutions de manière détaillée afin de fournir une expérience de développement plus agréable aux utilisateurs.
Si ce sujet vous intéresse, je vous invite vivement à visionner le replay de cette conférence.

Crédit photo : seb_ra