Introduction aux API et API-Platform

De nos jours, il est de plus en plus important, voire nécessaire, de permettre aux services en ligne d’être accessibles depuis diverses plateformes : un navigateur web, une application mobile, des objets connectés…

Le temps du simple site web est révolu, et, tant pour une question de coût que de maintenance, il n’est pas non plus question de dupliquer le code de notre logique métier pour chacun des canaux que l’on envisage. 

C’est ainsi qu’en toute logique, les APIs web sont peu à peu devenues incontournables, et ont fini par devancer les historiques Web Services.

Qu’est-ce qu’une API ?

Le terme API signifie (en anglais): Application Programming Interface. Une désignation un peu barbare mais qui résume bien notre besoin : fournir une Interface pour que les développeurs d’Applications puissent Programmer ce qui leur est demandé. Bien que nous nous concentrons uniquement sur les API Web ici, il est important de préciser qu’une API n’est pas forcément liée au Web, comme par exemple en Java, où il est possible d’appeler des fonctions distantes via le standard RMI (Remote Method Invocation).

Généralement, une API Web est fournie avec sa documentation qui permet d’exposer les services qu’elle propose et la description de leur utilisation.

Une des caractéristiques principales d’une API est qu’elle peut échanger de l’information dans des formats ouverts et non dépendants d’un langage en particulier. Ainsi, le développeur Web pourra utiliser facilement le format JSON, tandis que le développeur d’applications mobiles pourra utiliser le XML s’il le souhaite. Petit à petit, JSON à tendance à surpasser les autres formats, du fait de sa simplicité et légèreté comparé au XML, qui souffre d’un encombrement conséquent du fait de sa syntaxe en <balisage />.

Il existe plusieurs types d’API Web, les plus répandus étant: REST et SOAP. Historiquement, SOAP est plus souvent utilisé dans le cadre d’un Web Service. Cela dit, dans cet article, nous nous concentrerons exclusivement sur REST.

REST ?

REST est un standard qui a été cité pour la première fois en 2000 par Roy Fielding dans sa thèse « Architectural Styles and the Design of Network-based Software Architectures » (chapitre 5). C’est l’abréviation de Representational State Transfer.

REST est entièrement basé sur le protocole que l’on connaît bien: HTTP, et met à profit l’utilisation des Verbes HTTP (GET, POST, PUT, DELETE etc.) qui permettent une compréhension aisée des différentes actions possibles sur une API. 

Une API REST est dite RESTful.

La théorie

Pour faciliter la compréhension, nous allons imaginer le développement d’une Todo-List.

Lorsque l’on prépare une API REST, on a tendance à parler de Ressources. Les Ressources sont les modèles de notre application, ici les Listes et les Tâches. 

Voici une représentation de ce que pourrait donc donner notre API-Doc:

• GET /todolists : retourne les todo-lists
• POST /todolists : crée une todo-list 
• DELETE /todolists : supprime une todo-list
• PATCH /todolists : modifie les informations d’une todo-list
  
• GET /todos : retourne la liste des tâches
• POST /todos : crée une tâche
• DELETE /todos : supprime une tâche
• PATCH /todos : modifie une tâche

On s’aperçoit que les méthodes sont similaires pour chacune de nos Ressources, et que leur représentation est extrêmement comparable aux Modèles de notre application qui appliquent, avec Symfony en tous cas, le Design-Pattern MVC (Modèle-Vue-Controlleur). 

C’est précisément à ce moment qu’API-Platform entre en jeu et va nous permettre de ne pas coder “à la main” toutes ces routes et actions !

Qu’est-ce qu’API-Platform ?

API-Platform est une distribution Symfony qui permet de créer rapidement et simplement de puissantes API REST, au moyen de quelques annotations sur nos Entités. Initié par Kévin Dunglas (contributeur Core Symfony et fondateur des Tilleuls.coop), il est maintenant développé et maintenu par de grands noms de la communauté et fait partie des distributions officielles de Symfony (maintenant installées via l’outil Flex). 

API-Platform tire profit de nombreux composants Symfony, comme le Serializer, Validator, HTTPFoundation, EventDispatcher, Doctrine etc.

API-Platform permet non-seulement de créer rapidement une API REST, mais également sa documentation au format OpenAPI (ex Swagger). Il facilite également le support de nombreux formats en standard: JSON, JSON+LD (Hydra), XML…

Son développement rapide a permis d’intégrer rapidement de nombreuses fonctionnalités autour de l’API, comme le Cache HTTP via Varnish, le temps réel via Mercure, la Pagination automatique, GraphQL, ElasticSearch et bien d’autres encore… 

De plus, chacun des composants d’API-Platform fournit des Interfaces que nous pouvons implémenter pour adapter le comportement d’API-Platform à nos besoins.

Comment ça marche ?

C’est précisément là qu’API-Platform devient imbattable de simplicité : il suffit d’ajouter une simple Annotation sur nos Entités ! Oui oui, c’est tout 🙂

Dans notre exemple de Todo-list nous avons logiquement deux Entités : TodoList et Todo 

Comme vous pouvez le constater, une annotation a fait son apparition en ligne 14: @ApiResource

Et voilà ! Notre API est désormais fonctionnelle, avec sa documentation ! Pas besoin de Controlleur ou de configuration de routing. API-Platform a généré automatiquement pour chaque entité 6 routes par défaut:

• GET /todolists : liste toutes les todolists
• POST /todolists : création de todolist
• GET /todolists/{id} : affiche les détails d’une todolist en particulier
• DELETE /todolists/{id} : supprime une todolist en particulier
• PATCH /todolists/{id} : édite une todolist en particulier
• PUT /todolists/{id} : remplace une todolist
• GET /todos : liste toutes les tâches
• POST /todos : créé une tâche
• GET /todos/{id} : affiche les détails d’une tâche en particulier
• DELETE /todos/{id} : supprime une tâche en particulier
• PATCH /todos/{id} : édite une tâche en particulier
• PUT /todos/{id} : remplace une tâche en particulier

Comme vous pouvez le constater, API-Platform distingue les deux types d’opérations : 

• collectionOperations: les opérations sur des listes de Ressources
• itemOperations: les opérations sur des Ressources unitaires

Bien sûr, API-Platform vous permet d’activer et/où de désactiver une opération en particulier, ainsi que de customiser chacune des actions. Les informations qui sont remontées lors d’un GET peuvent être aisément configurées par le biais des groupes de sérialisation du Serializer Symfony. De même, les annotations du validateur sur nos propriétés permettent de remonter les erreurs lors des opérations POST, comme on le ferait pour un formulaire classique.

Conclusion

Il serait trop long de lister toutes les possibilités qu’API-Platform propose, mais ce simple exemple est une bonne image de toute la puissance que cet outil apporte, sans parler du gain de temps substantiel qu’il permet. Il est évidemment possible d’ajouter de l’authentification (avec JWT par exemple) en utilisant simplement le composant Security de Symfony.

Sa prise en main est vraiment simple pour un développeur Symfony. Les choses se compliquent un peu lorsqu’on souhaite sortir du schéma classique mais, là aussi, il sera relativement aisé de trouver de la documentation ou de l’aide en ligne tant la communauté autour de l’outil s’est développée au fil du temps.

Pour aller plus loin:

• Documentation officielle API-Platform : https://api-platform.com/docs/
• Talk d’introduction de Kévin Dunglas à l’AFUP Paris : https://www.youtube.com/watch?v=taGGa2MAyG4
• Slides de présentation d’API-Platform à l’occasion du SymfonyCon : https://www.slideshare.net/coopTilleuls/api-platform-and-symfony-a-framework-for-apidriven-projects