Every new Symfony project that needs to expose a REST API hits the same kickoff question: API Platform or plain controllers? A quick "API Platform, it's faster" answer tends to get paid back six months later, when the team is fighting the framework's abstractions for use cases that never fit the CRUD mold. Going fully manual on a straightforward admin backend is just as wasteful in the other direction. The right call depends on the actual shape of the domain, not a tooling preference.

What API Platform actually does

API Platform builds a full API from the metadata attached to a Doctrine entity. A single #[ApiResource] attribute gets you CRUD operations, OpenAPI documentation, JSON-LD/Hydra support, pagination, filtering, and content negotiation, with very little code.

#[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;

    // ...
}

What gets underestimated is that API Platform isn't limited to basic CRUD. Since version 3, the request lifecycle goes through a State Provider for reads and a State Processor for writes, replacing the older v2 DataProvider/DataPersister. That means arbitrary business logic can be plugged in without stepping outside the 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);
    }
}

The classic beginner mistake is assuming API Platform forces you to expose the raw Doctrine entity on the wire. You can decouple the API resource shape from the persistence model entirely using input/output DTOs on the operation, which keeps the public API contract independent from the database schema.

What a hand-built API costs, and what it buys

A manual API rebuilds every layer yourself: routing, deserialization, validation, serialization, pagination, documentation. The Symfony Serializer and Validator components are still available, so you're not starting from zero, but the wiring is explicit.

#[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']]);
}

The upside here isn't cosmetic: each endpoint takes exactly the shape the business logic requires, with no negotiation against framework conventions. When an endpoint has to orchestrate several aggregates, kick off an asynchronous workflow, or return a projection unrelated to any single table, a hand-written controller stays readable. With API Platform, you'd end up stacking custom State Processors and custom operations that bury the real logic under layers of configuration.

The real decision criterion

The question isn't "which one is faster to write", it's whether the API mostly exposes CRUD resources that mirror the data model, or orchestrates complex business use cases.

  • Back-office tools, admin interfaces, exposing reference data: API Platform wins almost every time. Automatic OpenAPI documentation and the Hydra client save weeks, and the standard filtering/sorting/pagination cover most needs out of the box.
  • Business APIs with complex rules, use-case-shaped endpoints (POST /orders/{id}/cancel, POST /invoices/{id}/send-reminder): a hand-built API, or API Platform restricted to State Processors on custom operations, keeps logic visible and testable without framework artifacts getting in the way.
  • A team unfamiliar with API Platform's abstractions: the learning curve on State Providers/Processors, nested serialization groups, and custom filters is real. A team that already knows the Symfony Serializer and Validator will move faster going manual on a small-to-medium surface.

The N+1 trap with raw exposed entities

A recurring problem with API Platform shows up when you expose Doctrine entities with their relations directly, without thinking it through: every collection response can trigger one query per lazily-loaded relation, which reproduces the classic N+1 problem already well known from ORMs in general. The fix isn't to drop API Platform, it's to control loading explicitly: #[ApiFilter] does nothing for this, you need to act at the State Provider level by forcing a fetch join or an explicit leftJoin/addSelect in the underlying query, or by using read-side DTOs that project directly from an optimized query.

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, errors, and versioning: two different philosophies

A point most surface-level comparisons skip is error handling. API Platform automatically converts Symfony Validator violations into RFC 7807-compliant responses (application/problem+json), with per-field detail, with no extra code required:

{
  "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." }
  ]
}

With a hand-built API, this format doesn't exist by default: it has to be built manually from ConstraintViolationListInterface, as in the controller example above, and kept consistent across every endpoint. That's not an unreasonable amount of work, but it's a recurring cost the team needs to budget for upfront if it wants a manual API with a consistent error contract, rather than letting every developer invent their own error response shape endpoint by endpoint.

Versioning follows the same logic. API Platform lets multiple versions of an operation coexist through distinct uriTemplate values or content negotiation headers, but the underlying resource stays a single entity, which complicates a genuine breaking change between v1 and v2 on the same resource. A hand-built API, by contrast, can duplicate a controller and its DTO for a new version without touching the existing one, at the cost of accepted code duplication. On a public API with external clients that can't migrate overnight, that second model gives more room to maneuver.

A concrete example: letting both coexist in the same project

A real project doesn't have to pick a single approach for its entire surface. A common setup activates API Platform only on a subset of reference-data entities, and exposes business use cases through plain controllers registered under a separate prefix:

# config/packages/api_platform.yaml
api_platform:
    mapping:
        paths:
            - '%kernel.project_dir%/src/Entity/Referential'

Entities under the Referential folder (categories, tax rates, payment methods) get the generated CRUD, while everything living in src/Controller/Api stays hand-written. This physical separation by folder makes the choice explicit for anyone adding a new resource: the "API Platform or manual" question gets asked once per entity, not once for the whole project.

When the "easy" fix isn't enough

Defaulting to API Platform everywhere because "it generates everything" becomes a liability as the application grows and half its resources end up with custom operations, providers and processors that essentially reimplement a manual API, just with API Platform's configuration overhead on top. The right move at that point is to segment: keep API Platform for the resources that are genuinely CRUD, and switch to manual controllers for use-case-shaped endpoints, inside the same Symfony project. The two coexist without friction since API Platform is itself just a set of standard Symfony bundles.

Conversely, starting everything manual on a project that turns out to be 80% reference-data exposure wastes real time reinventing pagination, filtering and OpenAPI documentation the framework already ships ready to use.

Takeaway

API Platform is the right default for an API that faithfully exposes a data model through standard CRUD operations: the velocity and documentation gains are real. Once most endpoints represent business use cases rather than resources, a hand-built API using the Symfony Serializer and Validator keeps the code more readable and easier to evolve. Both approaches coexist fine in the same project; the decision is made endpoint by endpoint, not at the project level.