Une opération API Platform décrit un point d’entrée de ta ressource : méthode HTTP, chemin, lecture ou écriture des données, sérialisation et règles de sécurité. Pour publier un catalogue en lecture seule, déclare explicitement une opération de collection et une opération de détail ; tu n’as pas besoin de réécrire les contrôleurs CRUD.
La vidéo d’origine concerne Symfony 6 et API Platform 3. Cet enrichissement s’appuie sur la
documentation des opérations et sur un exemple
exécuté avec PHP 8.4.26, API Platform 4.4.5, Symfony FrameworkBundle 7.4.21, Doctrine ORM 3.7.5 et
DBAL 4.5.0, avec SQLite. C’est une combinaison vérifiée, pas une affirmation sur la dernière
version disponible ni une validation de toutes les versions 3 et 4. Vérifie ton propre
composer.lock avant de transposer le code.
Choisir ce que ton API expose
Ne confonds pas la méthode HTTP et la portée de l’opération :
GetCollectionlit une liste, par exemple le catalogue des livres.Getlit un livre identifié par son URL.Postcrée généralement une ressource dans une collection.Patch,PutetDeleteconcernent ici une ressource individuelle ; leurs formats et leurs règles d’écriture demandent une configuration adaptée.
Le piège important : dès que tu déclares une opération explicitement, les opérations CRUD
implicites ne sont plus ajoutées à ta place. Si tu veux conserver la lecture du détail et de la
collection, déclare les deux. Ce comportement est expliqué dans la section
activer et désactiver les opérations.
N’ajoute donc pas un Get isolé en espérant conserver automatiquement les écritures.
Préparer une ressource Doctrine en lecture seule
Pars d’une application Symfony où API Platform et Doctrine ORM fonctionnent déjà : bundles
activés, connexion à une base locale de test, mapping des entités par attributs et découverte des
ressources dans src/Entity. Si tu pars de zéro, consulte d’abord le
tutoriel de création d’une API.
Ce guide se concentre sur le contrat HTTP, pas sur l’installation complète du projet.
Crée src/Entity/Book.php :
<?php
namespace App\Entity;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ApiResource(operations: [
new GetCollection(uriTemplate: '/catalog/books'),
new Get(uriTemplate: '/catalog/books/{id}', requirements: ['id' => '\d+']),
])]
class Book
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
public ?int $id = null;
#[ORM\Column(length: 255)]
public string $title = '';
#[ORM\Column]
public bool $published = false;
}
Les propriétés publiques rendent cet exemple court ; adapte ensuite les groupes de sérialisation
et l’encapsulation à ton domaine. Le champ published servira au
guide des extensions Doctrine : à ce stade,
aucun filtrage ne l’utilise. Un livre non publié reste donc lisible dans cet exemple d’opérations.
Vérifie l’import dans config/routes/api_platform.yaml : remplace une configuration équivalente,
ne l’ajoute pas une seconde fois.
api_platform:
resource: .
type: api_platform
prefix: /api
Les chemins des attributs sont relatifs à cet import : l’URL réelle devient
/api/catalog/books, pas /catalog/books. Pour préfixer toutes les opérations d’une seule
ressource, l’option routePrefix existe aussi ; voir la
configuration des préfixes.
Choisis un seul endroit pour chaque segment afin d’éviter un préfixe doublé.
Créer les données de test et vérifier le contrat
Dans ta base de développement uniquement, génère puis applique la migration correspondant à l’entité si Doctrine Migrations est installé :
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate
php bin/console debug:router
Ces commandes de migration sont une procédure documentée, non exécutée pour cet article : le bac à sable a créé directement le schéma SQLite avec Doctrine SchemaTool. Relis toujours la migration générée avant de l’appliquer ; voir la gestion du schéma avec Symfony et Doctrine.
Ajoute un livre via ton système de fixtures ou un script Doctrine local : title vaut
« Livre public » et published vaut true. Ajoute un second livre « Brouillon » avec false.
Aucun Post n’étant exposé, tu ne peux pas créer ces données avec l’API de cet exemple.
Récupère leurs identifiants réels, puis remplace 1 dans les requêtes ci-dessous si nécessaire.
Pour une application locale déjà démarrée sur le port 8000 :
curl -i -H 'Accept: application/ld+json' http://127.0.0.1:8000/api/catalog/books
curl -i -H 'Accept: application/ld+json' http://127.0.0.1:8000/api/catalog/books/1
curl -i -X POST -H 'Content-Type: application/ld+json' -d '{}' http://127.0.0.1:8000/api/catalog/books
curl -i -X DELETE http://127.0.0.1:8000/api/catalog/books/1
Résultats observés dans le bac à sable, avec les blocs PHP et YAML ci-dessus extraits de l’article et chargés dans un vrai kernel Symfony :
- la collection répond 200 et contient les deux livres ; le détail du livre existant répond 200 ;
- les identifiants JSON-LD des livres utilisent le chemin
/api/catalog/books/{id}; POSTsur la collection etDELETEsur le détail répondent 405 ;- un identifiant numérique inexistant répond 404 ;
/api/catalog/books/abcne correspond pas à la contrainte numérique et répond également 404.
Les réponses ont été contrôlées par des requêtes HTTP locales. Les migrations, le navigateur, l’authentification, les formats d’écriture et un déploiement ne font pas partie de cette validation. Dans ton projet, vérifie aussi le contenu de la réponse, pas seulement son statut : un 200 sur une collection vide ne prouve pas que ton mapping ou tes fixtures sont corrects.
Garder une URL de détail pour les IRI
Une IRI identifie une ressource, notamment dans le champ JSON-LD @id et dans les relations. Dans
l’exemple, le Get explicite fournit une URL de détail lisible et stable. Avec plusieurs Get,
la sélection de l’opération utilisée pour les IRI doit être réfléchie.
N’en déduis pas que toute ressource sans Get provoque forcément une erreur de sérialisation :
la documentation actuelle décrit une opération de secours, non documentée dans OpenAPI, qui
répond 404 pour permettre l’identification. La
section sur les IRI
distingue ce mécanisme d’un véritable endpoint de lecture. Ce cas de secours est documenté,
non testé ici. Conserve le Get de l’exemple si tu veux réellement consulter chaque livre.
Diagnostiquer les erreurs sans changer de couche
- Une écriture a disparu après l’ajout d’un attribut : relis la liste explicite des opérations. Ne réactive une méthode que si elle fait partie du contrat voulu.
- Un chemin renvoie 404 : contrôle le préfixe de l’import, le
uriTemplate, la contrainte de l’identifiant et la présence de la ligne en base. Le même statut peut avoir plusieurs causes. - Tu veux masquer les brouillons : modifier l’URL ne filtre pas les données. Utilise une extension Doctrine ORM pour modifier les requêtes de lecture, puis traite séparément les autorisations.
- Tu ajoutes un traitement métier : choisis un state provider pour fournir l’état et un state processor pour traiter une écriture. Un chemin personnalisé ne crée pas ce traitement à lui seul.
Pour replacer ces métadonnées dans le tutoriel historique Symfony 6 / API Platform 3, tu peux regarder la vidéo associée. Garde les vérifications HTTP comme critère de réussite dans ton projet.


