Série – Créer une API avec Symfony et API Platform

#1 Mise en place d'API Platform

Transformez votre application Symfony en API REST en quelques minutes

19 sept. 2020 à 17:33 – 6min


Table des matières

Bonjour et bienvenue dans cette nouvelle séries d'articles consacrée à la création d'une API avec Symfony et API Platform.

Mise en place du projet

Installation d'API Platform

Pour installer API Platform pour votre projet, rien de plus simple, ajoutez le bundle via Composer : 

symfony composer require api

Une fois le bundle installé, rendez-vous à la page /api, et voilà ! Votre page de documentation est maintenant disponible ! Certes, elle est un peu vide pour le moment, mais nous allons rapidement la remplir. 

Créer des entités

Maintenant que nous avons mis en place le bundle, essayons de créer quelques entités afin de rendre notre application un peu plus... utile. Nous allons dans cette série développer l'API d'un blog, avec des articles, des utilisateurs, des commentaires, etc. Je vous encourage bien sûr à appliquer ce que vous apprendrez ici à vos propres besoins. Si vous souhaitez partir sur le même projet que moi, vous pouvez cloner ce repo github. 

Configuration d'API Platform

Une fois vos entités créées, il va falloir les configurer pour être visibles par API Platform. Pour cela, API Platform propose deux types de configurations, via les annotations directement dans les classes des entités, ou via des fichiers yaml. Pour ma part, je vais opter pour la deuxième option, car cela me permettra de séparer la logique propre à API Platform du reste de mon application, et de tour réunir au même endroit. 

Pour cela, nous allons créer un nouveau dossier config/api_platform/. C'est dans ce dossier que nous allons ajouter tous nos fichiers de configuration propres à API Platform. 

Nous devons maintenant indiquer au bundle où aller chercher ces fichiers. Modifiez donc le fichier de configuration d'API Platform comme ceci :

Dans ce fichier, nous indiquons un tableau sous la clé mapping, qui permet d'indiquer où se trouve la configuration de nos entités, ici dans le dossier src/Entity/ (si vous utilisez des annotation), et dans le dossier config/api_platform/ que nous venons de créer (pour les fichiers .yaml). 

Le paramètre show_webby permet de supprimer l'animation de webby, l'arraignée d'API Platform qui apparait par défaut sur votre page de documentation. Nous reviendrons plus tard dans cette série sur l'utilité de la clé patch_formats. 

Pour le reste du fichier de configuration, c'est assez trivial. Vous pouvez indiquer la version de votre API, la version de Swagger utilisée (le standard de description de votre API, géré par le bundle), ainsi qu'une description supportant le Markdown.  

Configuration des entités

Exposer les opérations CRUD

Nous voilà au coeur du sujet. Nous allons maintenant indiquer à API Platform quelles entités utiliser, et comment s'en servir. Nous allons commencer très simplement en ajoutant un fichier article.yaml dans notre dossier config/api_platform/, qui contient uniquement la ligne suivante : 

Essayez d'actualiser la documentation de votre API, vous devriez voir quelques changements. 

Que s'est-il passé ? Nous venons simplement d'informer API Platform que nous voulons exposer notre entité Article via notre API. Comme nous n'avons rien configuré de plus, API Platform va, par défaut, exposer tous les opérations possibles pour lister, modifier ou supprimer nos articles.

Comme vous le voyez, vous pouvez utiliser cette page de documentation pour tester directement vos opérations. Essayez de jouer par vous même sur cette page en ajoutant, supprimant et modifiant quelques articles.

Pour utiliser la méthode POST, vous pouvez remarquer que le body par défaut contient un champ comments avec beaucoup, beaucoup d'informations. En effet, API Platform expose par défaut toutes les informations de l'entité User lié au commentaire. Pour le moment, essayez seulement de créer des articles sans commentaires, en passant donc un tableau vide ([]) au champ comments

Les formats

Essayez maintenant la commande symfony console debug:router. Vous allez voir toutes les routes exposées par votre API. Vous pouvez remarquer que chaque route peut être préfixée par un paramètre _format. En effet, API Platform propose par défaut différents formats permettant de représenter nos données : 

Néanmoins, API Platform est capable de gérer d'autres formats. Il est tout à fait possible de modifier les formats supportés par votre API, via le fichier de configuration du bundle. Pour illustrer ceci, nous allons ajouter le support du format CSV à notre API :

Actualisez votre documentation, ou utilisez la command debug:router, le format CSV est maintenant disponible ! 

C'est tout pour ce première article de notre série sur API Platform, rendez-vous dans le prochain article pour découvrir comment ordonner et filtrer vos ressources !