---
title: 'API Platform : choisir les opérations et personnaliser les routes'
description: 'Expose un catalogue en lecture seule avec Get et GetCollection, configure ses URL et vérifie les méthodes HTTP et les IRI de tes ressources.'
pubDate: 2023-07-28
updatedDate: 2026-10-19
family: 'php-symfony'
tags: []
heroImage: '/images/les-operations-avec-symfony-6-et-api-platform-3.webp'
videoUrl: 'https://www.youtube.com/watch?v=FSFwMxntHeM'
---

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](https://api-platform.com/docs/core/operations/) 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 :

- `GetCollection` lit une liste, par exemple le catalogue des livres.
- `Get` lit un livre identifié par son URL.
- `Post` crée généralement une ressource dans une collection.
- `Patch`, `Put` et `Delete` concernent 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](https://api-platform.com/docs/core/operations/#enabling-and-disabling-operations).
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](/blog/creer-une-api-avec-symfony-6-et-api-platform-3-en-30-minutes/).
Ce guide se concentre sur le contrat HTTP, pas sur l'installation complète du projet.

Crée `src/Entity/Book.php` :

```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](/blog/les-extensions-avec-symfony-6-et-api-platform-3/) : **à 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.

```yaml
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](https://api-platform.com/docs/core/operations/#prefixing-all-routes-of-all-operations).
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é :

```bash
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](https://symfony.com/doc/7.4/doctrine.html#migrations-creating-the-database-tables-schema).

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 :

```bash
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}` ;
- `POST` sur la collection et `DELETE` sur le détail répondent 405 ;
- un identifiant numérique inexistant répond 404 ; `/api/catalog/books/abc` ne 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](https://api-platform.com/docs/core/operations/#enabling-and-disabling-operations)
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](/blog/les-extensions-avec-symfony-6-et-api-platform-3/) pour modifier les
  requêtes de lecture, puis traite séparément les autorisations.
- **Tu ajoutes un traitement métier** : choisis un
  [state provider](https://api-platform.com/docs/core/state-providers/) pour fournir l'état et un
  [state processor](https://api-platform.com/docs/core/state-processors/) 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.
