API Platform - Une solution web puissante pour construire des APIs modernes

22/10/2024

Alexandre DA SILVA

API Platform ? Mais c'est quoi en fait

API Platform est un framework web, open-source basé sur Symfony, conçu pour faciliter la création d'APIs RESTful et GraphQL. Il offre des fonctionnalités prêtes à l'emploi qui réduisent le temps de développement tout en garantissant la flexibilité.
API Platform génère automatiquement des endpoints, des contrôles de validation, et même une documentation interactive grâce à Swagger ou OpenAPI, rendant le développement plus efficace.
Récemment d'ailleurs, API Platform peut être facilement installé sur de nouveaux ou des projets Laravel existants, comme précisé sur la documentation officielle.

Fonctionnalités et caractéristiques clés

- Création d'API REST grâce au CRUD automatisé
- Enregistrement automatique des routes
- Génération automatique de points d'entrée, avec accès à toute les ressources
- Hypermedia (JSON-LD, HAL)
- Documentation API au format Hydra, Swagger/Open Api, extraction des métadonnées PHPDoc, Serializer, Validator, ainsi que des ORM Doctrine et ODM MongoDB
- Gestion de lecture Elasticsearch
- Une sandbox accessible via SwaggerUI / ReDoc
- Des filtres de recherche, de tris, un système de pagination...
- Un système avancé sur la Serialization (support des "groups", relations, max depth)
- Des Validateurs avec le support des "groups", utilisant le composant Symfony Validator
- Un système de gestion avancé des règles d'authentification et d'accès
- Serialization des erreurs
- Prise en charge de l'authentification JWT et OAuth
et plein d'autres...

Pourquoi choisir API Platform pour vos projets ?

Aujourd'hui, il existe de nombreuses solutions web pour réaliser des applications. Chez Koul, on est fan (absolus) de Symfony / PHP et surtout du projet API Platform qu'on l'utilise pour tous nos projets API, complexes ou non.

Vous avez des projets robustes, scalables et avec des standards de l'industrie grâce au travail collaboratifs des contributeurs/trices

Simplicité et Rapidité : API Platform est conçu pour automatiser le processus de création d'API. Il génère automatiquement des endpoints CRUD basés sur vos entités, ce qui réduit considérablement le temps de développement.

Documentation Intégrée : Grâce à l'intégration de Swagger et OpenAPI, la documentation de votre API est générée instantanément, facilitant la collaboration avec d'autres développeurs ou équipes métier.

Flexibilité et Extensibilité : API Platform peut être facilement personnalisé pour répondre à des besoins spécifiques, et il s'intègre parfaitement aux fonctionnalités et composants Symfony.

REST et/ou GraphQL : vous avez le choix

API Platform prend en charge à la fois REST et GraphQL, offrant aux développeurs une flexibilité totale pour construire leurs APIs. Ces deux technologies ont des avantages distincts, permettant de répondre à différents besoins en matière de gestion des données.

REST : REST est une architecture bien établie qui repose sur des ressources accessibles via des endpoints. Il est idéal pour les opérations standardisées de type CRUD, où chaque endpoint renvoie un ensemble de données complet.

GraphQL: GraphQL, quant à lui, permet de requêter des données de manière plus fine. Les clients peuvent spécifier exactement les données dont ils ont besoin, ce qui réduit la quantité de données transférées et optimise les performances, particulièrement utile pour les applications nécessitant des réponses légères et rapides.

Performance et Optimisation

Cache HTTP et Validation : API Platform intègre des en-têtes ETag et Cache-Control pour optimiser les performances en réduisant le nombre de requêtes.

Optimisation de la Sérialisation : La sérialisation, comme vous l'avez vu plus haut peut être ajustée pour améliorer les performances, en ne sélectionnant que les champs nécessaires à chaque requête.

Personnalisation et Extensibilité

API Platform est hautement extensible. Vous pouvez personnaliser les opérations, utiliser des événements pour intercepter le cycle de vie d'une requête, et ajouter des fonctionnalités spécifiques en fonction de vos besoins.

Événements et Listeners : Les événements permettent d’ajouter de la logique avant ou après certaines actions de l’API, vous offrant un contrôle granulaire sur les opérations.

Voyons voir, dans la technique, comment cela se passe avec un mini tutoriel maison.

Tutoriel - Découvrir API Platform par Koul

On vous propose un mini tuto Koul qui va faire le tour des fonctionnalités, en utilisant la distribution complète et recommandée.
Pré-requis :
- Votre outil de gestion de containers préféré: Orbstack, Rancher Desktop, Docker Desktop ...
- Un petit café ☕
- Une copie de la base du projet de ce tutoriel

Vous avez également la possibilité de suivre la documentation officielle qui est claire et bien réalisée.

Installation du projet

1) Téléchargez le projet Koul : API Platform Tutoriel

curl -O https://storage.googleapis.com/koultutorial/koul_tutorial.tar.gz && tar -xzvf koul_tutorial.tar.gz && cd koul-base-tutorial

2) Ouvrir le dossier dans l'IDE de votre choix.
Nous utiliserons ici Visual Studio Code pour faciliter le tutoriel.

3) Démarrez votre outil de gestion de container préféré et lancez les commandes suivantes

docker compose build --no-cache
docker compose up --wait

Ces commandes servent à builder et démarrer vos différents services, via des conteneurs:
- php : Avec le serveur web Caddy, via FrankenPHP (avec support natif de Mercure, Vulcain et XDebug) + composer ainsi que votre dossier de travail monté.
- pwa : Un projet Next.js avec un Admin pré-installé
- database : Un serveur de base de données PostgreSQL

Si jamais vous souhaitez changer de ports d'accès, vous pouvez modifier cela depuis les fichiers compose.yaml et / ou compose.override.yaml

Lancement du projet et des jeux de données

Sur le projet proposé, 3 entités ont été créées ainsi que des Fixtures (des jeux de données).
C'est une simple api qui contient des Projets, créés par des Auteurs et qui contiennent des Tâches

Vous pouvez lancer cette commande composer, depuis votre host, qui va permettre d'appliquer les différentes migrations doctrine et de lancer les Fixtures.

docker compose exec php \
    composer init-tuto

ou bien directement dans votre container php

composer init-tuto

Dès lors que l'installation s'est bien déroulée, vous avez accès à une interface légèrement customisée Koul :

Vue /docs API Platform sur localhost

L'api : https://localhost/docs/ (dossier api/)

L'application Next.js : https://localhost/ (dossier pwa/)

L'interface d'administration https://localhost/admin (dossier pwa/pages/admin/)

Tuto - Modifier la serialization de l'entité Project

Pour vous montrer les possibilités, nous souhaitons modifier les éléments de normalization de l'entité Project
Le but est d'y apporter des modifications afin de retourner que les données que nous souhaitons.

Par défaut, une IRI est renvoyée lorsque vous avez des relations
Egalement, nous ne souhaitons pas retourner toutes les tâches du projet.
Ainsi, nous allons appliquer les modifications suivantes à l'entity Project

Image route /projects GET sur SwaggerUI

Ajout de groupes de serialization

1) Ajouter des contextes de normalization et de denormalization dans votre entity Project

// App\Entity\Project.php
...
#[ApiResource(
normalizationContext: ['groups' => ['project:read']],
denormalizationContext: ['groups' => ['project:write']],
)]
...

2) Importer l'annotation Groups et y ajouter les groupes aux champs suivants, sur l'entity Project

// App\Entity\Project.php
...
use Symfony\Component\Serializer\Annotation\Groups;
...

#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
#[Groups(['project:read'])]
private ?int $id = null;
  
#[ORM\Column(length: 255)]
#[Groups(['project:read'])]
private ?string $name = null;

#[ORM\Column]
#[Groups(['project:read'])]
private ?\DateTimeImmutable $createdAt = null;

#[ORM\Column]
#[Groups(['project:read'])]
private ?\DateTimeImmutable $updatedAt = null;

#[ORM\Column(type: Types::TEXT, nullable: true)]
#[Groups(['project:read'])]
private ?string $description = null;

#[ORM\ManyToOne(inversedBy: 'projects')]
#[Groups(['project:read'])]
private ?Author $author = null;

/**
* @var Collection<int, Task>
*/
#[ORM\OneToMany(mappedBy: 'project', targetEntity: Task::class)]
private Collection $tasks;
...

3) Ajouter les champs souhaités de votre Entity Author

// App\Entity\Author.php
...
use Symfony\Component\Serializer\Annotation\Groups;
...

#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;

#[ORM\Column(length: 255)]
#[Groups(['project:read'])]
private ?string $firstname = null;

#[ORM\Column(length: 255)]
#[Groups(['project:read'])]
private ?string $lastname = null;
...

Dès lors les données retournées, pour les routes GET de l'entité Projet vont changer et s'adapter selon vos groupes.

Il s'agit d'un exemple standard, vous pouvez y retrouver toutes les possibilités sur la documentation officielle

Vue des données retournées de la route /projects en GET

Ajout d'un filtre de recherche

Dans cet exemple, on souhaite faire une recherche par nom(champ lastname) de l'entité Author relation de l'entité Project

1) On importe la classe prévus par API Platform pour l'utilisation des filtres de recherche : SearchFilter
2) On ajoute l'annotation ApiFilter qui va utiliser les les classes que l'on souhaite

Dans l'énoncé, on souhaite pouvoir rechercher par nom de famille

// App\Entity\Project.php
...
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Metadata\ApiFilter;
...

#[ApiFilter(
    SearchFilter::class,
    properties: ['author.lastname' => 'partial']
)]
class Project
...

Ainsi, lors d'une requête sur la liste des Projets (route GET /projects), je peux filtrer et obtenir les résultats suivants (les données peuvent varier selon les fixtures)

Vues retour données api de la route /projects en Get

Ajout d'un filtre de tri, par défaut, sur le champ difficulty de l'entité Task

Dans cet exemple, on souhaite simplement faire en sorte, que les tâches soient ordonnées par le champ difficulty, par ordre décroissant.

// App\Entity\Task.php
...

#[ApiResource(order: ['difficulty' => 'DESC'])]
class Task
...

Ainsi, je retrouve par défaut, toutes mes données avec le tri respecté.
Il s'agit d'un exemple standard, vous pouvez y retrouver toutes les possibilités sur la documentation officielle

Vue des données retournées de la routes /tasks

Nous vous proposerons toute une série d'articles spécifiques pour chaque cas intéressants d'API Platform

Conclusion

API Platform est une solution puissante qui simplifie la création d'APIs modernes et maintenables. Grâce à ses fonctionnalités automatisées, sa documentation intégrée, et sa flexibilité, API Platform est un excellent choix pour les développeurs Symfony et / ou Laravel, souhaitant construire des APIs robustes, tout en gagnant du temps. Essayez API Platform et découvrez par vous-même à quel point le développement d'APIs peut être simple et efficace.

Ressources et Documentation

Documentation officielle d'API Platform : https://api-platform.com/docs/

Si vous avez une API ou un projet web sur mesure, nous développons les logiciels qui répondent à vos besoins ! Contactez nous