Sur un nouveau projet Symfony qui doit exposer une API REST, la question revient systématiquement en réunion de lancement : API Platform ou contrôleurs faits main ? La réponse donnée trop vite ("API Platform, ça va plus vite") se paie souvent six mois plus tard, quand l'équipe se retrouve à contourner les abstractions du framework pour des cas qui ne rentrent pas dans le moule CRUD. À l'inverse, écrire une API manuelle sur un simple module d'administration de données est aussi une perte de temps. Le bon choix dépend de la forme réelle du domaine, pas d'une préférence d'outillage.
Ce qu'API Platform fait réellement
API Platform génère une API complète à partir des métadonnées d'une entité Doctrine. Avec un attribut #[ApiResource], on obtient en quelques lignes les opérations CRUD, la documentation OpenAPI, le support JSON-LD/Hydra, la pagination, le filtrage et la négociation de contenu.
#[ApiResource(
operations: [
new GetCollection(),
new Get(),
new Post(security: "is_granted('ROLE_ADMIN')"),
new Put(security: "is_granted('ROLE_ADMIN')"),
new Delete(security: "is_granted('ROLE_ADMIN')"),
],
normalizationContext: ['groups' => ['invoice:read']],
denormalizationContext: ['groups' => ['invoice:write']],
)]
#[ApiFilter(SearchFilter::class, properties: ['status' => 'exact', 'client.name' => 'partial'])]
#[ApiFilter(OrderFilter::class, properties: ['createdAt'])]
class Invoice
{
#[Groups(['invoice:read'])]
private ?Uuid $id = null;
#[Groups(['invoice:read', 'invoice:write'])]
#[Assert\NotBlank]
private string $reference;
// ...
}
Ce qui est souvent sous-estimé : API Platform ne se limite pas au CRUD basique. Depuis la version 3, le cycle de traitement d'une requête passe par des State Provider (lecture) et State Processor (écriture), qui remplacent les anciens DataProvider/DataPersister de la v2. On peut donc brancher une logique métier arbitraire sans sortir du framework.
final class InvoiceStateProcessor implements ProcessorInterface
{
public function __construct(
private ProcessorInterface $persistProcessor,
private InvoiceNumberGenerator $generator,
) {}
public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
{
if ($data instanceof Invoice && null === $data->getReference()) {
$data->setReference($this->generator->next());
}
return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
}
}
C'est l'erreur de débutant classique : croire qu'API Platform oblige à exposer directement l'entité Doctrine sur le fil. On peut parfaitement découpler la ressource API du modèle de persistance avec un DTO en entrée/sortie (input/output sur l'opération), ce qui évite de coupler le schéma de la base à la forme de l'API publique.
Ce que coûte une API manuelle, et ce qu'elle rapporte
Une API manuelle reconstruit chaque brique : routage, désérialisation, validation, sérialisation, pagination, documentation. Le Symfony Serializer et le composant Validator restent disponibles, donc on ne part pas de zéro, mais le câblage est explicite.
#[Route('/api/invoices', name: 'invoice_create', methods: ['POST'])]
public function create(
Request $request,
SerializerInterface $serializer,
ValidatorInterface $validator,
InvoiceService $invoiceService,
): JsonResponse {
$dto = $serializer->deserialize($request->getContent(), CreateInvoiceDto::class, 'json');
$violations = $validator->validate($dto);
if (count($violations) > 0) {
return $this->json(['errors' => (string) $violations], Response::HTTP_UNPROCESSABLE_ENTITY);
}
$invoice = $invoiceService->createFromDraft($dto);
return $this->json($invoice, Response::HTTP_CREATED, [], ['groups' => ['invoice:read']]);
}
L'avantage n'est pas cosmétique : chaque endpoint a la forme exacte que le métier exige, sans négocier avec les conventions du framework. Quand un endpoint doit orchestrer plusieurs agrégats, déclencher un workflow asynchrone ou renvoyer une projection qui n'a aucun rapport avec une table, le contrôleur manuel reste lisible. Avec API Platform, on finirait par empiler des State Processor et des opérations custom qui masquent la logique réelle derrière des couches de configuration.
Le vrai critère de décision
La question à se poser n'est pas "API Platform est-il plus rapide à écrire", mais : est-ce que l'API expose majoritairement des ressources CRUD alignées sur le modèle de données, ou orchestre-t-elle des cas d'usage métier complexes ?
- Back-office, interfaces d'administration, exposition de référentiels : API Platform gagne presque toujours. La génération automatique de la documentation OpenAPI et du client Hydra fait gagner des semaines, et les filtres/tri/pagination standards couvrent 90 % des besoins.
- API métier avec règles complexes, endpoints orientés cas d'usage (
POST /orders/{id}/cancel,POST /invoices/{id}/send-reminder) : une API manuelle, ou une API Platform cantonnée aux State Processors sur des opérations personnalisées, garde la logique visible et testable sans artefacts de framework. - Équipe peu familière avec les abstractions d'API Platform : la courbe d'apprentissage des
State Provider/Processor, des groupes de sérialisation imbriqués et des filtres personnalisés n'est pas négligeable. Une équipe qui maîtrise déjà le Serializer et le Validator Symfony ira plus vite en manuel sur un périmètre petit à moyen.
Le piège du N+1 et des entités exposées brutes
Un problème récurrent avec API Platform survient quand on expose directement des entités Doctrine avec leurs relations, sans y réfléchir : chaque collection retournée déclenche potentiellement une requête par relation chargée en lazy, ce qui reproduit le classique problème N+1 déjà connu dans les ORMs. La solution n'est pas d'abandonner API Platform mais de maîtriser le chargement : #[ApiFilter] ne résout rien ici, il faut agir au niveau du State Provider en forçant un fetch join ou en utilisant addSelect/leftJoin explicite dans le repository sous-jacent, ou en passant par des DTO en lecture qui projettent directement le résultat d'une requête optimisée.
final class InvoiceCollectionProvider implements ProviderInterface
{
public function __construct(private EntityManagerInterface $em) {}
public function provide(Operation $operation, array $uriVariables = [], array $context = []): iterable
{
return $this->em->createQueryBuilder()
->select('i', 'c')
->from(Invoice::class, 'i')
->leftJoin('i.client', 'c')
->getQuery()
->getResult();
}
}
Validation, erreurs et versioning : deux philosophies différentes
Un point que les comparatifs superficiels oublient presque toujours est la gestion des erreurs. API Platform convertit automatiquement les violations du Validator Symfony en réponses conformes à la RFC 7807 (application/problem+json), avec le détail de chaque champ en faute, sans code supplémentaire :
{
"type": "/errors/422",
"title": "An error occurred",
"detail": "reference: This value should not be blank.",
"status": 422,
"violations": [
{ "propertyPath": "reference", "message": "This value should not be blank." }
]
}
En API manuelle, ce format n'existe pas par défaut : il faut le construire soi-même à partir de ConstraintViolationListInterface, comme dans l'exemple de contrôleur plus haut, et le maintenir cohérent sur chaque endpoint. Ce n'est pas un travail insurmontable, mais c'est un coût récurrent que l'équipe doit budgétiser dès le départ si elle veut une API manuelle au contrat d'erreur homogène, plutôt que de laisser chaque développeur inventer sa propre forme de réponse d'erreur endpoint par endpoint.
Le versioning suit la même logique. API Platform permet de faire cohabiter plusieurs versions d'une opération via des uriTemplate distincts ou des en-têtes de négociation de contenu, mais la ressource sous-jacente reste unique, ce qui complique un vrai changement de contrat entre v1 et v2 sur une même entité. Une API manuelle, à l'inverse, peut dupliquer un contrôleur et son DTO pour une nouvelle version sans toucher à l'existant, au prix d'une duplication de code assumée. Sur une API publique avec des clients externes qui ne peuvent pas migrer du jour au lendemain, ce second modèle donne plus de marge de manœuvre.
Un exemple concret : faire cohabiter les deux dans le même projet
Un projet réel n'a pas à choisir une seule approche pour l'ensemble de son périmètre. Une configuration fréquente consiste à activer API Platform uniquement sur un sous-ensemble d'entités de référentiel, et à exposer les cas d'usage métier via des contrôleurs classiques enregistrés sous un préfixe distinct :
# config/packages/api_platform.yaml
api_platform:
mapping:
paths:
- '%kernel.project_dir%/src/Entity/Referential'
Les entités du dossier Referential (catégories, taxes, modes de paiement) bénéficient du CRUD généré, tandis que tout ce qui vit dans src/Controller/Api reste écrit à la main. Cette séparation physique par dossier rend le choix explicite pour quiconque ajoute une nouvelle ressource : la question "API Platform ou manuel" se pose une fois par entité, pas une fois pour tout le projet.
Quand l'approche "facile" ne suffit pas
Partir sur API Platform par défaut parce que "ça génère tout" devient un problème quand l'application grossit et que la moitié des ressources finit avec des opérations custom, des providers et des processors qui réimplémentent en fait une API manuelle, mais avec la verbosité de configuration d'API Platform en plus. Dans ce cas, le bon réflexe est de segmenter : garder API Platform pour les ressources réellement CRUD, et basculer en contrôleurs manuels pour les endpoints orientés cas d'usage, dans le même projet Symfony. Les deux coexistent sans friction puisqu'API Platform reste un ensemble de bundles Symfony standards.
Inversement, démarrer tout en manuel sur un projet qui s'avère être à 80 % de l'exposition de référentiels fait perdre un temps précieux à réinventer pagination, filtres et documentation OpenAPI que le framework offre déjà prêts à l'emploi.
À retenir
API Platform est le bon choix par défaut pour une API qui expose fidèlement un modèle de données avec des opérations CRUD standards : le gain de vélocité et de documentation est réel. Dès que la majorité des endpoints représentent des cas d'usage métier plutôt que des ressources, une API manuelle avec le Serializer et le Validator Symfony garde le code plus lisible et plus facile à faire évoluer. Les deux approches cohabitent très bien dans un même projet : le critère de choix se pose endpoint par endpoint, pas au niveau du projet entier.
