Symfony 7: API Platform y Mejores Practicas

Guia completa para crear APIs REST profesionales con Symfony 7 y API Platform 4. State Providers, Processors, validacion y serializacion explicados.

Guia de API Platform 4 con Symfony 7: mejores practicas para APIs REST en PHP

API Platform 4 transforma la creacion de APIs REST y GraphQL con Symfony. La version 4.4, publicada en septiembre de 2026, incorpora filtros composables, la depreciacion de los decoradores #[ApiFilter] y soporte nativo para OpenAPI 3.2. Combinado con el contenedor de servicios y autowiring de Symfony, construir una API profesional resulta sencillo.

Novedades en API Platform 4.4

La version 4.4 deprecia los decoradores #[ApiFilter] heredados (eliminacion prevista para la 6.0) a favor de filtros composables como ComparisonFilter, OrFilter y ChainFilter. Scalar UI reemplaza a Swagger UI por defecto desde la 4.3, y OpenAPI 3.2 cuenta con soporte completo. Consulte las notas de la version oficial para la guia de migracion.

Instalacion y Configuracion Inicial

API Platform se instala en pocos comandos con Symfony Flex. La configuracion predeterminada cubre la mayoria de los casos de uso y permanece totalmente personalizable.

bash
# terminal
# Create a new Symfony project with API Platform
composer create-project symfony/skeleton my-api
cd my-api

# Install API Platform with Doctrine ORM
composer require api

# Verify installation
php bin/console debug:router | grep api

Symfony Flex configura automaticamente las rutas, la documentacion OpenAPI y la interfaz Scalar UI accesible en /api. La documentacion de API Platform detalla todas las opciones de configuracion.

yaml
# config/packages/api_platform.yaml
api_platform:
    title: 'My API'
    version: '1.0.0'
    # Supported response formats
    formats:
        jsonld: ['application/ld+json']
        json: ['application/json']
    # OpenAPI documentation
    swagger:
        versions: [3]
    # Default pagination
    defaults:
        pagination_items_per_page: 30
        pagination_maximum_items_per_page: 100

Esta configuracion define los formatos de serializacion, la paginacion global y los metadatos de documentacion de la API.

Creacion de un Recurso API Simple

El atributo #[ApiResource] expone una entidad Doctrine como recurso REST. API Platform genera automaticamente los endpoints CRUD, la documentacion OpenAPI y las validaciones basicas.

php
<?php
// src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    // Explicit definition of available operations
    operations: [
        new GetCollection(),
        new Post(),
        new Get(),
        new Put(),
        new Patch(),
        new Delete(),
    ],
    // Default ordering for collections
    order: ['publishedAt' => 'DESC'],
    // Pagination configuration for this resource
    paginationItemsPerPage: 20
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank(message: 'Title is required')]
    #[Assert\Length(min: 2, max: 255)]
    private ?string \ = null;

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    private ?string \ = null;

    #[ORM\Column(length: 13, unique: true)]
    #[Assert\Isbn]
    private ?string \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
    public function getId(): ?int
    {
        return \->id;
    }

    public function getTitle(): ?string
    {
        return \->title;
    }

    public function setTitle(string \): static
    {
        \->title = \;
        return \;
    }

    public function getDescription(): ?string
    {
        return \->description;
    }

    public function setDescription(string \): static
    {
        \->description = \;
        return \;
    }

    public function getIsbn(): ?string
    {
        return \->isbn;
    }

    public function setIsbn(string \): static
    {
        \->isbn = \;
        return \;
    }

    public function getPublishedAt(): ?\DateTimeImmutable
    {
        return \->publishedAt;
    }

    public function setPublishedAt(\DateTimeImmutable \): static
    {
        \->publishedAt = \;
        return \;
    }
}

Esta entidad genera seis endpoints: GET /api/books, POST /api/books, GET /api/books/{id}, PUT /api/books/{id}, PATCH /api/books/{id} y DELETE /api/books/{id}.

UUID v7 Recomendado

API Platform soporta nativamente UUID v7 como identificadores. Este enfoque mejora la seguridad (identificadores no predecibles) y el rendimiento (ordenamiento natural por fecha de creacion).

Grupos de Serializacion para Controlar Datos Expuestos

Los grupos de serializacion definen con precision que propiedades se exponen para lectura (normalizacion) y escritura (desnormalizacion). Esta separacion es esencial para la seguridad y flexibilidad de la API. Para escenarios de serializacion complejos, el componente Serializer de Symfony ofrece opciones adicionales de personalizacion.

php
<?php
// src/Entity/User.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
use App\State\UserPasswordHasher;

#[ORM\Entity]
#[ORM\Table(name: '`user`')]
#[UniqueEntity('email')]
#[ApiResource(
    operations: [
        new GetCollection(),
        // Custom processor for password hashing
        new Post(processor: UserPasswordHasher::class,
                 validationContext: ['groups' => ['Default', 'user:create']]),
        new Get(),
        new Put(processor: UserPasswordHasher::class),
        new Patch(processor: UserPasswordHasher::class),
        new Delete(),
    ],
    // Properties exposed when reading
    normalizationContext: ['groups' => ['user:read']],
    // Properties accepted when writing
    denormalizationContext: ['groups' => ['user:create', 'user:update']],
)]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['user:read'])]
    private ?int \ = null;

    #[ORM\Column(length: 180, unique: true)]
    #[Assert\NotBlank]
    #[Assert\Email]
    #[Groups(['user:read', 'user:create', 'user:update'])]
    private ?string \ = null;

    #[ORM\Column]
    private ?string \ = null;

    // Never exposed when reading, only when writing
    #[Assert\NotBlank(groups: ['user:create'])]
    #[Groups(['user:create', 'user:update'])]
    private ?string \ = null;

    #[ORM\Column(length: 100)]
    #[Groups(['user:read', 'user:create', 'user:update'])]
    private ?string \ = null;

    #[ORM\Column(type: 'json')]
    #[Groups(['user:read'])]
    private array \ = [];

    #[ORM\Column]
    #[Groups(['user:read'])]
    private ?\DateTimeImmutable \ = null;

    public function __construct()
    {
        \->createdAt = new \DateTimeImmutable();
    }

    // UserInterface implementation
    public function getUserIdentifier(): string
    {
        return (string) \->email;
    }

    public function getRoles(): array
    {
        \ = \->roles;
        \[] = 'ROLE_USER';
        return array_unique(\);
    }

    public function getPassword(): string
    {
        return \->password;
    }

    public function eraseCredentials(): void
    {
        \->plainPassword = null;
    }

    // Getters and setters...
    public function getId(): ?int
    {
        return \->id;
    }

    public function getEmail(): ?string
    {
        return \->email;
    }

    public function setEmail(string \): static
    {
        \->email = \;
        return \;
    }

    public function setPassword(string \): static
    {
        \->password = \;
        return \;
    }

    public function getPlainPassword(): ?string
    {
        return \->plainPassword;
    }

    public function setPlainPassword(?string \): static
    {
        \->plainPassword = \;
        return \;
    }

    public function getFullName(): ?string
    {
        return \->fullName;
    }

    public function setFullName(string \): static
    {
        \->fullName = \;
        return \;
    }

    public function setRoles(array \): static
    {
        \->roles = \;
        return \;
    }

    public function getCreatedAt(): ?\DateTimeImmutable
    {
        return \->createdAt;
    }
}

Con esta configuracion, plainPassword nunca se expone en las respuestas pero puede enviarse durante la creacion o actualizaciones.

¿Listo para aprobar tus entrevistas de Symfony?

Practica con nuestros simuladores interactivos, flashcards y tests técnicos.

State Processors para Logica de Negocio

Los State Processors interceptan las operaciones de persistencia para agregar logica de negocio. API Platform simplifica su creacion mediante inyeccion de dependencias basada en atributos.

php
<?php
// src/State/UserPasswordHasher.php

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\User;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

/**
 * Processor that hashes password before persistence
 * @implements ProcessorInterface<User, User>
 */
final class UserPasswordHasher implements ProcessorInterface
{
    public function __construct(
        // Injection of standard Doctrine processor
        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
        private ProcessorInterface \,
        private UserPasswordHasherInterface \,
    ) {
    }

    public function process(mixed \, Operation \, array \ = [], array \ = []): User
    {
        // Hash password if provided
        if (\->getPlainPassword()) {
            \ = \->passwordHasher->hashPassword(
                \,
                \->getPlainPassword()
            );
            \->setPassword(\);
            \->eraseCredentials();
        }

        // Delegate persistence to standard processor
        return \->persistProcessor->process(\, \, \, \);
    }
}

Este patron de composicion permite agregar cualquier logica (envio de correos, eventos, logs) conservando el comportamiento estandar de persistencia. Para arquitecturas event-driven, los processors se integran perfectamente con Symfony Messenger.

Processor con Logica Condicional

Un processor puede adaptar su comportamiento segun el tipo de operacion.

php
<?php
// src/State/BookProcessor.php

namespace App\State;

use ApiPlatform\Metadata\DeleteOperationInterface;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\Metadata\Post;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\Book;
use App\Service\NotificationService;
use App\Service\SearchIndexer;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

/**
 * @implements ProcessorInterface<Book, Book|void>
 */
final class BookProcessor implements ProcessorInterface
{
    public function __construct(
        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
        private ProcessorInterface \,
        #[Autowire(service: 'api_platform.doctrine.orm.state.remove_processor')]
        private ProcessorInterface \,
        private NotificationService \,
        private SearchIndexer \,
    ) {
    }

    public function process(mixed \, Operation \, array \ = [], array \ = []): mixed
    {
        // Deletion: use remove processor
        if (\ instanceof DeleteOperationInterface) {
            \->searchIndexer->remove(\);
            return \->removeProcessor->process(\, \, \, \);
        }

        // Creation: set publication date
        if (\ instanceof Post) {
            \->setPublishedAt(new \DateTimeImmutable());
        }

        // Standard persistence
        \ = \->persistProcessor->process(\, \, \, \);

        // Post-processing: indexing and notification
        \->searchIndexer->index(\);

        if (\ instanceof Post) {
            \->notifications->notifyNewBook(\);
        }

        return \;
    }
}

State Providers para Fuentes de Datos Personalizadas

Los State Providers obtienen datos de cualquier fuente: APIs externas, cache, archivos o logica de negocio compleja.

php
<?php
// src/State/PopularBooksProvider.php

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\Entity\Book;
use App\Repository\BookRepository;
use Symfony\Contracts\Cache\CacheInterface;
use Symfony\Contracts\Cache\ItemInterface;

/**
 * Provider that returns popular books with caching
 * @implements ProviderInterface<Book>
 */
final class PopularBooksProvider implements ProviderInterface
{
    public function __construct(
        private BookRepository \,
        private CacheInterface \,
    ) {
    }

    public function provide(Operation \, array \ = [], array \ = []): array
    {
        // 5-minute cache for popular books
        return \->cache->get('popular_books', function (ItemInterface \) {
            \->expiresAfter(300);

            return \->bookRepository->findPopular(limit: 10);
        });
    }
}

Este provider se utiliza en una operacion dedicada.

php
<?php
// src/Entity/Book.php (excerpt)

use App\State\PopularBooksProvider;

#[ApiResource(
    operations: [
        // ... other operations
        new GetCollection(
            uriTemplate: '/books/popular',
            provider: PopularBooksProvider::class,
            paginationEnabled: false,
        ),
    ],
)]
class Book
{
    // ...
}

Validacion Avanzada con Grupos Dinamicos

API Platform integra nativamente el componente Validator de Symfony. Los grupos de validacion pueden variar segun la operacion o el contexto.

php
<?php
// src/Entity/Article.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    operations: [
        new GetCollection(),
        new Get(),
        // Strict validation on creation
        new Post(validationContext: ['groups' => ['Default', 'article:create']]),
        // More lenient validation for updates
        new Put(validationContext: ['groups' => ['Default', 'article:update']]),
    ],
)]
class Article
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

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

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    // Minimum 500 characters on creation
    #[Assert\Length(min: 500, groups: ['article:create'])]
    // Minimum 100 characters for updates
    #[Assert\Length(min: 100, groups: ['article:update'])]
    private ?string \ = null;

    #[ORM\Column(length: 50)]
    #[Assert\NotBlank(groups: ['article:create'])]
    #[Assert\Choice(choices: ['draft', 'published', 'archived'])]
    private ?string \ = 'draft';

    #[ORM\Column(nullable: true)]
    // Required only if status is "published"
    #[Assert\NotBlank(groups: ['article:publish'])]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
}

Validacion Dinamica con un Servicio

Para reglas de validacion complejas, un generador de grupos personalizado ofrece flexibilidad total.

php
<?php
// src/Validator/ArticleGroupsGenerator.php

namespace App\Validator;

use ApiPlatform\Symfony\Validator\ValidationGroupsGeneratorInterface;
use App\Entity\Article;
use Symfony\Bundle\SecurityBundle\Security;

final class ArticleGroupsGenerator implements ValidationGroupsGeneratorInterface
{
    public function __construct(
        private Security \,
    ) {
    }

    public function __invoke(object \): array
    {
        assert(\ instanceof Article);

        \ = ['Default'];

        // Admins have fewer restrictions
        if (\->security->isGranted('ROLE_ADMIN')) {
            \[] = 'admin';
            return \;
        }

        // Additional validation if publishing
        if (\->getStatus() === 'published') {
            \[] = 'article:publish';
        }

        return \;
    }
}
Rendimiento de Validacion

Las validaciones complejas pueden impactar el rendimiento. Para importaciones masivas, considere deshabilitar temporalmente ciertas validaciones o utilizar constraints asincronas.

Filtros para Consultas Flexibles

API Platform 4.4 redisena el sistema de filtros con filtros composables. El decorador heredado #[ApiFilter] esta depreciado (eliminacion prevista para la 6.0), y hay un codemod disponible para la migracion.

php
<?php
// src/Entity/Product.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource]
// Text search on name and description
#[ApiFilter(SearchFilter::class, properties: [
    'name' => 'partial',       // LIKE %value%
    'description' => 'partial',
    'category.name' => 'exact', // Search on relation
    'sku' => 'exact',          // Exact match
])]
// Range filtering
#[ApiFilter(RangeFilter::class, properties: ['price', 'stock'])]
// Date filtering
#[ApiFilter(DateFilter::class, properties: ['createdAt', 'updatedAt'])]
// Boolean filtering
#[ApiFilter(BooleanFilter::class, properties: ['isActive', 'isFeatured'])]
// Customizable sorting
#[ApiFilter(OrderFilter::class, properties: [
    'name',
    'price',
    'createdAt',
], arguments: ['orderParameterName' => 'sort'])]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    private ?string \ = null;

    #[ORM\Column(type: 'text', nullable: true)]
    private ?string \ = null;

    #[ORM\Column(length: 50, unique: true)]
    private ?string \ = null;

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2)]
    private ?string \ = null;

    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column]
    private ?bool \ = true;

    #[ORM\Column]
    private ?bool \ = false;

    #[ORM\ManyToOne(targetEntity: Category::class)]
    private ?Category \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    #[ORM\Column(nullable: true)]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
}

Estos filtros generan automaticamente documentacion OpenAPI y habilitan consultas como:

text
GET /api/products?name=phone&price[gte]=100&price[lte]=500&isActive=true&sort[price]=asc

API Platform 4.4 introduce nuevos filtros: StartSearchFilter, EndSearchFilter, WordStartSearchFilter, y wrappers composables como ComparisonFilter, OrFilter y ChainFilter.

Relaciones y Subrecursos

API Platform maneja elegantemente las relaciones entre entidades con opciones de serializacion y subrecursos.

php
<?php
// src/Entity/Author.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Link;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

#[ORM\Entity]
#[ApiResource(
    normalizationContext: ['groups' => ['author:read']],
)]
class Author
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['author:read', 'book:read'])]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Groups(['author:read', 'book:read'])]
    private ?string \ = null;

    #[ORM\Column(type: 'text', nullable: true)]
    #[Groups(['author:read'])]
    private ?string \ = null;

    #[ORM\OneToMany(mappedBy: 'author', targetEntity: Book::class)]
    #[Groups(['author:read'])]
    private Collection \;

    public function __construct()
    {
        \->books = new ArrayCollection();
    }

    // Getters and setters...
}
php
<?php
// src/Entity/Book.php (with relation)

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Link;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

#[ORM\Entity]
#[ApiResource(
    normalizationContext: ['groups' => ['book:read']],
)]
// Subresource: GET /api/authors/{authorId}/books
#[ApiResource(
    uriTemplate: '/authors/{authorId}/books',
    operations: [new GetCollection()],
    uriVariables: [
        'authorId' => new Link(
            fromProperty: 'books',
            fromClass: Author::class
        ),
    ],
    normalizationContext: ['groups' => ['book:read']],
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['book:read', 'author:read'])]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Groups(['book:read', 'author:read'])]
    private ?string \ = null;

    #[ORM\ManyToOne(targetEntity: Author::class, inversedBy: 'books')]
    #[ORM\JoinColumn(nullable: false)]
    #[Groups(['book:read'])]
    private ?Author \ = null;

    // Getters and setters...
}

Seguridad y Control de Acceso

API Platform se integra perfectamente con el sistema de seguridad de Symfony. Voters y expresiones de seguridad controlan el acceso a los recursos. Para una vision completa de los patrones de seguridad de Symfony, consulte Symfony Security: Voters, Firewalls y preguntas de entrevista.

php
<?php
// src/Entity/Order.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(
    operations: [
        // List: authenticated users see their orders
        new GetCollection(
            security: "is_granted('ROLE_USER')",
            // Automatic filter by connected user
            provider: UserOrdersProvider::class,
        ),
        // Creation: any authenticated user
        new Post(
            security: "is_granted('ROLE_USER')",
            processor: CreateOrderProcessor::class,
        ),
        // Read: owner or admin
        new Get(
            security: "is_granted('ROLE_ADMIN') or object.getCustomer() == user",
            securityMessage: "Access denied to this order.",
        ),
        // Modification: admin only
        new Patch(
            security: "is_granted('ROLE_ADMIN')",
        ),
        // Deletion: admin only
        new Delete(
            security: "is_granted('ROLE_ADMIN')",
        ),
    ],
)]
class Order
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\ManyToOne(targetEntity: User::class)]
    #[ORM\JoinColumn(nullable: false)]
    private ?User \ = null;

    #[ORM\Column(length: 50)]
    private ?string \ = 'pending';

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2)]
    private ?string \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    // Getters...
    public function getCustomer(): ?User
    {
        return \->customer;
    }
}

La expresion object.getCustomer() == user permite acceder a la entidad actual y al usuario conectado para verificaciones granulares.

Pruebas Automatizadas de API

API Platform proporciona traits de PHPUnit para probar endpoints facilmente.

php
<?php
// tests/Api/BookTest.php

namespace App\Tests\Api;

use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
use App\Entity\Book;
use App\Factory\BookFactory;
use App\Factory\UserFactory;
use Zenstruck\Foundry\Test\Factories;
use Zenstruck\Foundry\Test\ResetDatabase;

class BookTest extends ApiTestCase
{
    use ResetDatabase;
    use Factories;

    public function testGetCollection(): void
    {
        // Create test data
        BookFactory::createMany(30);

        // GET request on collection
        \ = static::createClient()->request('GET', '/api/books');

        // Assertions
        \->assertResponseIsSuccessful();
        \->assertResponseHeaderSame('content-type', 'application/ld+json; charset=utf-8');
        \->assertJsonContains([
            '@context' => '/api/contexts/Book',
            '@type' => 'Collection',
            'totalItems' => 30,
        ]);
        // Verify pagination (20 items per page)
        \->assertCount(20, \->toArray()['member']);
    }

    public function testCreateBook(): void
    {
        \ = UserFactory::createOne(['roles' => ['ROLE_ADMIN']]);

        static::createClient()->request('POST', '/api/books', [
            'auth_bearer' => \->getToken(\),
            'json' => [
                'title' => 'Clean Code',
                'description' => 'A Handbook of Agile Software Craftsmanship',
                'isbn' => '9780132350884',
            ],
        ]);

        \->assertResponseStatusCodeSame(201);
        \->assertJsonContains([
            '@type' => 'Book',
            'title' => 'Clean Code',
        ]);
    }

    public function testCreateBookValidationFails(): void
    {
        \ = UserFactory::createOne(['roles' => ['ROLE_ADMIN']]);

        static::createClient()->request('POST', '/api/books', [
            'auth_bearer' => \->getToken(\),
            'json' => [
                'title' => '', // Empty title = error
                'isbn' => 'invalid-isbn',
            ],
        ]);

        \->assertResponseStatusCodeSame(422);
        \->assertJsonContains([
            '@type' => 'ConstraintViolationList',
            'violations' => [
                ['propertyPath' => 'title', 'message' => 'Title is required'],
            ],
        ]);
    }

    private function getToken(object \): string
    {
        // Implementation depends on your authentication system
        return 'test_token';
    }
}

Fuentes

Checklist de mejores practicas API Platform Symfony

API Platform con Symfony representa el estado del arte para crear APIs REST profesionales en PHP. La separacion clara entre State Providers (lectura) y State Processors (escritura), combinada con grupos de serializacion y el sistema de validacion, permite construir APIs robustas y mantenibles.

Checklist para APIs de calidad

  • Utilizar grupos de serializacion distintos para lectura y escritura
  • Implementar State Processors para logica de negocio (hash de contrasena, notificaciones)
  • Configurar filtros para busqueda y ordenamiento (migrar de los decoradores #[ApiFilter] depreciados a filtros composables)
  • Aplicar validaciones por operacion con grupos
  • Proteger endpoints con expresiones de seguridad
  • Escribir pruebas funcionales para cada endpoint
  • Documentar la API mediante metadatos OpenAPI

¡Empieza a practicar!

Pon a prueba tu conocimiento con nuestros simuladores de entrevista y tests técnicos.

La filosofia de API Platform privilegia la composicion sobre la herencia, y la configuracion sobre la convencion. El resultado: APIs escalables, testeables y conformes con los estandares REST/JSON-LD, listas para produccion desde el primer dia.

Reto diario

¿Sabrías detectar el bug en Symfony?

Un fragmento real, un bug oculto, un intento al día. Sin cuenta para probar.

Anthony Fillion-Maillet

Escrito por

Anthony Fillion-Maillet

Fundador de SharpSkill

Desarrollador fullstack desde hace más de 10 años. Dirige SharpSkill y responde por todo lo que se publica aquí.

Actualizado el 12 de octubre de 2026

Etiquetas

#symfony
#api platform
#php
#rest api
#api development

Compartir

Artículos relacionados