REST Controller Conventions (Symfony, no API Platform)

Controller shape

• One final class per resource, #[Route] prefix on the class.
• Constructor injection of services only (no repositories — see layered-architecture).
• Map the request body with #[MapRequestPayload] and query params with #[MapQueryString] into DTOs.
• Return JsonResponse via $this->json(...) with explicit status codes.

#[Route('/api/orders')]
final class OrderController extends AbstractController
{
    public function __construct(private readonly OrderService $orders) {}

    #[Route('', methods: ['GET'])]
    public function list(#[MapQueryString] OrderListQuery $query): JsonResponse
    {
        $page = $this->orders->list($query);

        return $this->json($page, context: ['groups' => ['order:read']]);
    }

    #[Route('/{id}', methods: ['GET'])]
    public function show(Uuid $id): JsonResponse
    {
        return $this->json(
            $this->orders->get($id),
            context: ['groups' => ['order:read', 'order:detail']],
        );
    }

    #[Route('', methods: ['POST'])]
    public function create(#[MapRequestPayload] CreateOrderRequest $request): JsonResponse
    {
        $order = $this->orders->createOrder($request);

        return $this->json(
            OrderResponse::fromEntity($order),
            Response::HTTP_CREATED,
            ['Location' => $this->generateUrl('order_show', ['id' => $order->getId()])],
            ['groups' => ['order:read']],
        );
    }

    #[Route('/{id}', methods: ['DELETE'])]
    public function delete(Uuid $id): JsonResponse
    {
        $this->orders->cancel($id);

        return new JsonResponse(null, Response::HTTP_NO_CONTENT);
    }
}

HTTP status codes

Don't return 200 for everything. Map domain exceptions to status codes in an exception listener (see problem-details-rfc9457).

Serialization groups, not entity exposure

Never serialize a Doctrine entity straight to the client without scoping. Either map to a response DTO or apply #[Groups] and pass the group in the serialization context.

// On the entity / DTO
#[Groups(['order:read'])]
private string $customerEmail;

#[Groups(['order:detail'])]   // only on the detail endpoint
private array $internalNotes;

Request mapping & validation

#[MapRequestPayload] deserializes and validates the DTO (via the Validator). On constraint failure it throws automatically → your exception listener turns it into a 422.

public function create(#[MapRequestPayload] CreateOrderRequest $request): JsonResponse

Validate query params the same way with #[MapQueryString]. See dto-and-validation.

Pagination

Return a stable envelope, never a bare array, so you can add metadata without a breaking change:

{
  "data": [ ... ],
  "page": 1,
  "perPage": 20,
  "total": 137
}

return $this->json(new PaginatedResponse($items, $page, $perPage, $total), context: ['groups' => ['order:read']]);

Cap perPage server-side. For deep pages, prefer keyset pagination (see doctrine-query-optimization).

Routing conventions

• Plural nouns: /orders, /orders/{id}, /orders/{id}/lines.
• No verbs in paths (/orders POST, not /createOrder).
• Use HTTP methods for actions; reserve sub-resources for relationships.
• Constrain params: #[Route('/{id}', requirements: ['id' => Requirement::UUID])].

Gotchas

• Agent returns $this->json($entity) without groups — scope with #[Groups] or map to a DTO; otherwise lazy associations serialize and leak fields.
• Agent returns 200 for created/deleted resources — use 201 (+ Location) and 204.
• Agent decodes JSON by hand (json_decode($request->getContent())) — use #[MapRequestPayload] + DTO.
• Agent puts verbs in routes (/getOrders, /createOrder) — use nouns + HTTP methods.
• Agent returns a bare JSON array for collections — use a paginated envelope.
• Agent catches NotFoundException in the controller — let the exception listener map it to 404.
• Agent skips param requirements — constrain {id} to UUID to avoid route collisions.