Créer une API REST complète avec API Platform 3

API Platform 3 : le guide complet

API Platform reste la solution de référence pour construire des API REST et GraphQL avec Symfony. La version 3 s'appuie sur Symfony 7 et simplifie la déclaration des ressources, la validation et la documentation. Ce tutoriel vous fait passer de zéro à une API REST utilisable en production : ressources, filtres, pagination, documentation OpenAPI, validation et authentification.

Prérequis

Une base Symfony 7 fonctionnelle (voir les nouveautés de Symfony 7 si vous migrez depuis une version antérieure) et une base de données configurée avec Doctrine ORM. API Platform 3 s'installe par-dessus, sans rien casser de votre application existante.

Installation et configuration

composer require api

Cette commande installe le bundle API Platform et son moteur de sérialisation. Le point d'entrée /api expose immédiatement une documentation interactive vide, prête à recevoir vos premières ressources.

Créer votre première ressource

Une ressource API Platform est une classe Doctrine annotée avec l'attribut #[ApiResource]. Les opérations CRUD (lecture, liste, création, modification, suppression) sont générées automatiquement, sans contrôleur à écrire :

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
        new Post(),
        new Put(),
        new Delete(),
    ],
    paginationItemsPerPage: 20,
    security: "is_granted('ROLE_USER')"
)]
#[ORM\Entity]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank]
    #[Assert\Length(min: 3, max: 255)]
    private ?string $name = null;

    #[ORM\Column(type: Types::DECIMAL, precision: 10, scale: 2)]
    #[Assert\Positive]
    private ?string $price = null;
}

L'attribut security restreint l'accès aux utilisateurs authentifiés : sans authentification en place, ces routes restent fermées (voir la section sécurité plus bas).

Filtres et recherche

API Platform expose des filtres déclaratifs, sans logique de requête à écrire à la main :

#[ApiFilter(SearchFilter::class, properties: ['name' => 'partial'])]
#[ApiFilter(RangeFilter::class, properties: ['price'])]
#[ApiFilter(OrderFilter::class, properties: ['name', 'price'])]
class Product
{
    // ...
}

SearchFilter gère la recherche textuelle partielle, RangeFilter les bornes numériques (price[gte]=10&price[lte]=50), OrderFilter le tri. Combinés, ils couvrent la majorité des besoins d'une API REST côté client sans filtre sur mesure.

Pagination

La pagination est activée par défaut (paginationItemsPerPage: 20 dans l'exemple ci-dessus). Chaque collection retournée inclut le nombre total d'éléments et les liens de navigation. Sur une ressource avec plusieurs milliers de lignes, ajustez la taille de page et envisagez une pagination par curseur plutôt que par décalage : au-delà de quelques dizaines de milliers de lignes, le décalage classique devient coûteux en base.

Documentation automatique

API Platform génère une documentation OpenAPI complète à partir du code, accessible sur /api/docs en Swagger UI et /api/docs.json au format brut. Chaque ressource, chaque filtre, chaque contrainte de validation apparaît automatiquement : rien à maintenir à la main, la documentation ne peut pas se désynchroniser du code.

Validation

La validation s'appuie sur les contraintes du composant Symfony Validator (#[Assert\NotBlank], #[Assert\Length], #[Assert\Positive]...). Une requête qui viole une contrainte renvoie automatiquement une réponse 422 avec le détail des champs en erreur, au format Hydra ou JSON:API selon la négociation de contenu.

Sécuriser votre API

Une API REST exposée sans authentification est une API REST exposée à tout le monde. API Platform s'intègre nativement avec l'authentification JWT : jetons courts, renouvellement automatique, et contrôle d'accès par ressource via l'attribut security vu plus haut. Pour des règles plus fines qu'un simple rôle, les Voters Symfony prennent le relais.

Versionner votre API

Une API REST complète doit aussi survivre à ses propres évolutions. API Platform ne gère pas le versioning nativement : la stratégie la plus simple reste le préfixe d'URL, avec une période de coexistence des deux versions le temps que vos clients migrent. Détail des stratégies de versioning et des politiques de fin de vie sur la page dédiée.

Aller plus loin

Ce guide couvre la création d'une API REST classique. API Platform expose aussi un schéma GraphQL depuis les mêmes ressources, sans code additionnel : utile si vos clients ont besoin de choisir finement les champs récupérés. Pour un exemple de mise en production à l'échelle, notre intégration Ojin AI illustre l'authentification d'un agent IA tiers consommant une API Platform.

Si vous préférez confier la création de votre API REST à quelqu'un qui l'a déjà fait en production, la page dédiée à la création d'API REST détaille l'accompagnement.

FAQ API Platform 3

Qu'est-ce qu'API Platform ?

Un framework PHP construit sur Symfony qui génère une API REST et GraphQL complète à partir de vos entités Doctrine : opérations CRUD, filtres, pagination, validation et documentation OpenAPI, sans contrôleur à écrire pour les cas standards.

API Platform 3 fonctionne-t-il avec Symfony 7 ?

Oui, c'est la combinaison recommandée. Si votre application tourne encore sur une version antérieure, voir les nouveautés de Symfony 7 avant de migrer.

Comment sécuriser une API créée avec API Platform ?

Par authentification JWT, native à API Platform : jetons courts, renouvellement automatique, contrôle d'accès par ressource via l'attribut security. Pour des règles métier plus fines, les Voters Symfony prennent le relais.

API Platform génère-t-il vraiment une documentation automatique ?

Oui, une documentation OpenAPI complète, générée depuis le code : ressources, filtres et contraintes de validation y apparaissent sans intervention manuelle.

Quelle différence entre une API REST Symfony écrite à la main et une API REST API Platform ?

Écrite à la main, chaque route, chaque contrôleur, chaque validation et chaque page de documentation se codent et se maintiennent séparément. Avec API Platform, les opérations CRUD, les filtres, la pagination et la documentation sont générés à partir de la seule déclaration de la ressource : le gain de vitesse est net sur les APIs orientées ressources, moins évident sur des logiques métier très spécifiques qui sortent du CRUD.