---
title: 'Créer une API avec Symfony 6 et API Platform 3 en 30 minutes'
description: 'Monter une API REST avec Symfony et API Platform : installation actuelle, entité exposée, schéma, requêtes de contrôle, différences avec la 3.x, erreurs courantes et limites.'
pubDate: 2023-05-15
updatedDate: 2026-10-27
family: 'php-symfony'
tags: []
heroImage: '/images/creer-une-api-avec-symfony-6-et-api-platform-3-en-30-minutes.webp'
videoUrl: 'https://www.youtube.com/watch?v=cYoNDoa4_jE'
---

Exposer une entité Doctrine en API REST complète, avec documentation OpenAPI, pagination et validation, tient en une installation et une classe annotée. La vidéo en bas de page a été enregistrée sur Symfony 6 et API Platform 3. Le titre reste, mais le parcours ci-dessous suit la version courante : **API Platform 5.0**, dont la dernière publication est la 5.0.5 du 23 octobre 2026 ([Packagist](https://packagist.org/packages/api-platform/core)). La branche 4.4 reste maintenue en correctifs et c'est la dernière 4.x ([notes de version](https://api-platform.com/docs/changelog)).

Le montage est **documenté mais non exécuté** pour cet article : aucune base ni aucun serveur n'a tourné ici. Les commandes viennent de la documentation officielle, le résultat attendu aussi.

## Ce qui change par rapport à la 3.x

Trois écarts suffisent à casser un copier-coller d'un vieux tutoriel.

L'attribut n'est plus `ApiPlatform\Core\Annotation\ApiResource` mais `ApiPlatform\Metadata\ApiResource` depuis la 3.0 ([guide de migration 3.0](https://github.com/api-platform/docs/blob/3.0/core/upgrade-guide.md)). Les opérations ne se déclarent plus en `collectionOperations` et `itemOperations`, mais dans `operations` avec des objets comme `new Get()` ou `new Post()`, et chaque opération peut porter sa propre configuration ([opérations](https://api-platform.com/docs/core/operations/)). Enfin la 5.0 change un défaut JSON:API : `use_iri_as_id` passe à `false`, l'identifiant de l'entité devient l'`id` du document ([guide de mise à jour](https://api-platform.com/docs/core/upgrade-guide/)).

## Prérequis

- PHP 8.2 minimum pour `api-platform/core` 5.x ([Packagist](https://packagist.org/packages/api-platform/core)) et Composer.
- La CLI Symfony pour `symfony new` et `symfony serve` ([installation](https://symfony.com/doc/current/setup.html)).
- Une base de données. SQLite suffit pour un essai : `DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db"` est le format donné par la documentation Symfony ([configuration Doctrine](https://symfony.com/doc/current/doctrine.html)).

## Installation

```bash
symfony new bookshop-api
cd bookshop-api
symfony composer require api
```

`api` est l'alias Flex du pack API Platform ; il installe le composant serveur, le pont Doctrine ORM et les dépendances Symfony utiles ([démarrage](https://api-platform.com/docs/symfony/)). Installé dans une application existante, API Platform expose ses routes sous le préfixe `/api`. Crée la base :

```bash
php bin/console doctrine:database:create
```

## Exposer une entité

Crée l'entité, puis ajoute l'attribut et le mapping. Une version minimale suffit pour vérifier la chaîne complète :

```php
use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource]
class Book
{
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    #[ORM\Column]
    public string $title = '';

    #[ORM\Column(nullable: true)]
    public ?string $isbn = null;
}
```

Les propriétés publiques sont acceptées par API Platform, Doctrine et Symfony : c'est le choix de la documentation pour aller vite ([tutoriel](https://api-platform.com/docs/symfony/)). Crée le schéma :

```bash
php bin/console doctrine:schema:create
symfony serve
```

## Vérifier que ça répond

Ouvre `https://localhost:8000/api` : l'interface OpenAPI liste les opérations générées pour `Book`. En ligne de commande, demande explicitement du JSON-LD, le format par défaut :

```bash
curl -H 'Accept: application/ld+json' https://localhost:8000/api/books
```

Tu obtiens une collection Hydra : `@context`, `@id`, `@type` valant `hydra:Collection`, et un tableau `hydra:member` vide au départ. Crée un livre :

```bash
curl -X POST https://localhost:8000/api/books \
  -H 'Content-Type: application/ld+json' \
  -H 'Accept: application/ld+json' \
  -d '{"title": "PHP moderne"}'
```

La réponse contient la ressource créée et son IRI. Relance le GET : le livre apparaît dans `hydra:member`. La pagination se déclenche au-delà de 30 éléments et se règle dans la configuration ([pagination](https://api-platform.com/docs/core/pagination/)). Si tu préfères du JSON sans vocabulaire, remplace l'en-tête `Accept` par `application/json` : la négociation de contenu est native ([formats](https://api-platform.com/docs/core/content-negotiation/)).

## Les erreurs qui arrivent vraiment

- `406 Not Acceptable` : l'en-tête `Accept` demande un format qui n'est pas activé. Reste sur `application/ld+json` ou `application/json`, ou active le format voulu.
- `404` sur `/api/books` alors que la classe existe : l'attribut vient d'un ancien namespace, l'entité n'est pas mappée par Doctrine, ou le cache est chaud. Corrige l'import, vérifie `#[ORM\Entity]`, puis `php bin/console cache:clear`.
- Une exception Doctrine au premier appel (`no such table`, ou pilote manquant) : le schéma n'a pas été créé, ou l'extension PDO de ta base n'est pas installée. Reprends `doctrine:database:create` et `doctrine:schema:create`, ou passe par une migration.

## Limites

Cette base n'a aucune authentification : toutes les opérations sont ouvertes, ce qui suffit pour un prototype mais pas pour une API exposée. Elle ne couvre pas non plus les tests fonctionnels, les filtres, ni les groupes de sérialisation. `symfony composer require api` installe la dernière version compatible, ici la 5.x : si tu dois rester en 4.4, épingle `api-platform/symfony` et `api-platform/doctrine-orm` en `^4.4`. Enfin, `PUT` n'est pas activé par défaut, et `PATCH` reste la mise à jour partielle documentée.

Pour verrouiller les accès, l'article sur les [scopes et l'authentification par clé API](/blog/systeme-de-scopes-et-authentification-via-cle-api-avec-symfony-7-et-api-platform-4/) prend la suite avec le même socle. La vidéo en bas de page montre le montage d'origine ; les commandes ci-dessus sont la version documentée pour la 5.0.
