Développer une API REST avec Symfony

1. Les concepts de REST

REST est un acronyme signifiant REpresentational State Transfer. L’idée est de placer une application dans un état de représentation de ses ressources en fonction de l’action demandée. Cette architecture de construction d’application s’appuie sur le protocole HTTP et sur la notion de ressource.

REST n’est pas à proprement parler un standard dans la mesure où...

1. Présentation du format JSON

Le format JSON (JavaScript Object Notation) est un format de données textuel inspiré de la notation des objets JavaScript, créé à partir de 2002 par Douglas Crockford. L’objectif du format JSON est de faciliter les échanges de données applicatives sur le Web, échanges qui étaient auparavant systématiquement basés sur XML. Ce dernier étant jugé trop verbeux et donc consommateur de bande passante, JSON constitue une alternative plus légère pour ces échanges.

1. Le service serializer

Avant de nous permettre de manipuler des données en JSON, il est nécessaire d’installer le sérialiseur Symfony. Ce sérialiseur sera ensuite disponible sous forme d’un service injectable dans les classes de votre application.

Pour installer ce service nommé serializer, il faut exécuter une recette Flex avec la commande suivante :

composer require symfony/serializer-pack 

Une fois installé, le service est injectable dans les actions de contrôleur via l’interface Symfony\Component\Serializer\SerializerInterface :

namespace App\Controller;  
  
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; 
use Symfony\Component\Serializer\SerializerInterface;  
  
class DefaultController extends AbstractController  ...

use Symfony\Component\Serializer\SerializerInterface;  
use Symfony\Component\HttpFoundation\Request;  
use Symfony\Component\HttpFoundation\Response;  
  
...  
  
public function creer(Request $request, SerializerInterface  
$serializer): Response  
{  
   ...  
} 

1. Le contenu et les en-têtes de requête

Lors de la manipulation des données entrantes, il est nécessaire de pouvoir récupérer les en-têtes et le corps de la requête.

Les en-têtes contiennent notamment le type de données envoyées par le client. Cette information est accessible via la méthode getContentType().

Dans le cas où des données JSON sont transmises dans la requête, elles le sont dans le corps ; ce contenu est accessible avec la méthode getContent().

Voici comment pourrait être structuré le code d’une action recevant un flux JSON en HTTP POST :

#[Route( 
       '/api/article', 
       name: 'api_article_creer', 
       methods: ['POST'] 
)] 
public function creer(  
   Request $request, SerializerInterface $serializer  
): Response  
{  
   // On contrôle le format de données...

1. Les limites du navigateur web

Dans le cadre du développement d’une application web traditionnelle utilisant des vues, il est assez simple de constater le rendu des pages grâce à son navigateur web.

Pour une API REST c’est différent. En effet, nous pourrons toujours l’utiliser pour tester les actions qui réagissent sur des requêtes HTTP de type GET, mais pour les requêtes POST, PUT et DELETE c’est compliqué, le navigateur n’est pas prévu pour cela.

Bien sûr, nous pouvons créer des tests fonctionnels s’appuyant sur PHPUnit et les objets Client et Crawler, comme évoqué dans le chapitre Tester son application Symfony, mais il est tout de même pratique de pouvoir consulter les réponses renvoyées par l’API dans les phases de développement. Nous allons pour cela utiliser des outils dédiés au test d’API REST.

2. Les outils

Les outils de test des API REST ne sont ni plus ni moins que des générateurs de requêtes HTTP permettant de recevoir et d’explorer des réponses HTTP. En véritables outils pour le développeur, ils permettent de regrouper les requêtes en projets ainsi que de spécifier les éventuels en-têtes et contenu de ces requêtes.

1. Présentation

API Platform est une librairie qui permet de créer simplement des API REST. Cette librairie est maintenue par Les Tilleuls.coop (https://les-tilleuls.coop) une entreprise française. Il existe un package permettant d’utiliser toute la souplesse d’API Platform dans Symfony et créer ainsi des API REST en un temps record !

2. Installation

Pour disposer du package API Platform dans son projet, il faut exécuter la recette Symfony correspondante à l’aide de la commande :

composer require api 

Une fois la recette exécutée, API Platform est en place. Vous pouvez en valider l’installation en navigant à l’adresse http://<monsite>/api.

Pour le moment, aucune opération n’est disponible, mais cela va changer rapidement à l’aide de quelques attributs ou annotations sur les entités Doctrine de l’application. 

3. La configuration d’API Platform

Au-delà de la librairie installée dans le dossier vendor/ du projet Symfony, d’autres fichiers sont apportés par l’installation d’API Platform, notamment :

Exemple de personnalisation :

api_platform:  
    title: "API REST pour MonJournal !"  ...