API Platform für Symfony: REST- und GraphQL-APIs, die skalieren

Jedes Symfony-Team, das eine datengetriebene SaaS-Anwendung baut, kommt irgendwann an dieselbe Weggabelung. Du hast zwölf Doctrine-Entities, eine wachsende Liste von React-Frontend-Anforderungen und einen Junior-Entwickler, der gerade die vierte handgeschriebene Paginierungsimplementierung in die Codebase eingefügt hat - jede ein bisschen anders als die vorherige. Filter sind über Controller-Queries verstreut. Die OpenAPI-Dokumentation ist chronisch veraltet. Und der GraphQL-Endpunkt, den dein Mobile-Team vor drei Monaten angefragt hat, ist immer noch ein offenes Ticket.

Das ist der Moment, in dem API Platform aufhört, eine Framework-Kuriosität zu sein, und zu einer Engineering-Entscheidung wird.

Was API Platform wirklich liefert (jenseits des Tutorials)

Die offizielle Dokumentation verkauft API Platform als Werkzeug zum "Erstellen hypermedia-gesteuerter REST- und GraphQL-APIs". Das ist korrekt, unterschätzt aber, was automatisch herausfällt, sobald du eine Klasse mit #[ApiResource] annotierst.

Aus der Box heraus liefert ein einziges Attribut: vollständige CRUD-Operationen auf der Ressource, JSON-LD- und Hydra-Serialisierung, eine Live-OpenAPI-3.1-Spezifikation unter /api/docs, Paginierung mit konfigurierbaren Seitengrößen, ein Filtersystem für Exact Match, Range, Datum, Suche und Reihenfolge, Symfony-Validator-Integration, event-gesteuerte Erweiterungspunkte über State Processors und Provider sowie einen optionalen GraphQL-Endpunkt, der deine gesamte API-Oberfläche abdeckt.

Das ist keine Tutorial-Vereinfachung - das ist produktionsreife Infrastruktur, die du nicht selbst schreiben musst. Für eine typische B2B-SaaS-Anwendung mit fünfzehn bis dreißig Ressourcen entspricht das wochenlanger Arbeit, die dein Team stattdessen in Produktdifferenzierung stecken kann.

#[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')"),
    ],
    paginationItemsPerPage: 25,
)]
#[ApiFilter(SearchFilter::class, properties: ['name' => 'partial', 'status' => 'exact'])]
#[ApiFilter(OrderFilter::class, properties: ['createdAt', 'name'])]
class Organisation
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    public int $id;

    #[ORM\Column]
    #[Assert\NotBlank]
    public string $name;

    #[ORM\Column(enumType: OrganisationStatus::class)]
    public OrganisationStatus $status = OrganisationStatus::Active;

    #[ORM\Column]
    public \DateTimeImmutable $createdAt;
}

Vierzig Zeilen annotierte Entity, und du hast eine gefilterte, paginierte, dokumentierte REST-API mit rollenbasierter Zugriffskontrolle. Die OpenAPI-Spezifikation aktualisiert sich automatisch. Dein Frontend-Team kann sie sofort in Postman importieren.

GraphQL ohne Rewrite

GraphQL in API Platform zu aktivieren erfordert ein Paket und eine Konfigurationszeile:

composer require webonyx/graphql-php

# config/packages/api_platform.yaml
api_platform:
    graphql:
        enabled: true
        graphiql:
            enabled: '%kernel.debug%'

Jede #[ApiResource]-Klasse ist sofort als GraphQL-Typ mit Queries, Mutations und cursor-basierter Paginierung verfügbar. Das Schema wird aus deinen bestehenden Serialisierungsgruppen abgeleitet, was bedeutet, dass du keine zwei separaten API-Definitionen pflegst.

Wo die meisten Teams auf Probleme stoßen, sind N+1-Queries - eine Query für eine Liste von Bestellungen, die verschachtelte Kundendaten enthält, kann eine Datenbankabfrage pro Zeile auslösen. API Platform stellt dies über Doctrines EagerLoadingExtension bereit, aber die richtige Lösung ist meist ein eigener State Provider mit einer Vorlade-Strategie für komplexe Lesevorgänge:

final class OrderCollectionProvider implements ProviderInterface
{
    public function __construct(
        private readonly OrderRepository $repository,
        private readonly CustomerRepository $customerRepository,
    ) {}

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): iterable
    {
        $orders = $this->repository->findWithFilters($context['filters'] ?? []);
        
        // Verwandte Daten batch-laden
        $customerIds = array_unique(array_map(fn($o) => $o->customerId, $orders));
        $customers = $this->customerRepository->findByIds($customerIds);
        
        return array_map(
            fn($order) => $order->withCustomer($customers[$order->customerId]),
            $orders
        );
    }
}

Diesen Provider mit provider: OrderCollectionProvider::class an eine Ressource zu knüpfen gibt dir volle Kontrolle über die Query-Strategie, ohne die API-Platform-Infrastruktur drumherum aufzugeben.

Security, DTOs und die Muster, die die Dokumentation übergeht

Das eingebaute security-Attribut auf Operationen behandelt einfache Rollenprüfungen gut. Für object-level access control - wo ein Nutzer nur die Daten seiner eigenen Organisation lesen kann - brauchst du Symfonys Voter-System kombiniert mit securityPostDenormalize auf Schreiboperationen:

#[ApiResource(
    operations: [
        new GetCollection(
            security: "is_granted('ROLE_USER')",
            provider: UserScopedCollectionProvider::class,
        ),
        new Put(
            security: "is_granted('ROLE_USER')",
            securityPostDenormalize: "is_granted('EDIT', object)",
        ),
    ],
)]

securityPostDenormalize läuft, nachdem die eingehenden Daten auf das Objekt angewendet wurden - genau dann hat dein Voter Zugriff auf die vollständig hydratisierte Entity, um die Eigentümerschaft zu prüfen. Das ist das Muster, das du für jede Multi-Tenant-SaaS willst: der Voter wird zum einzigen Durchsetzungspunkt, unabhängig davon, ob die Anfrage über REST oder GraphQL eingeht.

Für Schreiboperationen mit komplexen Validierungsregeln oder Feldern, die auf der Entity-Ebene nicht exponiert werden sollen, entkoppeln DTOs die API-Oberfläche vom Doctrine-Modell:

final class CreateInvitationInput
{
    #[Assert\Email]
    #[Assert\NotBlank]
    public string $email;

    #[Assert\Choice(['admin', 'member', 'viewer'])]
    public string $role = 'member';
}

#[Post(
    uriTemplate: '/organisations/{id}/invitations',
    input: CreateInvitationInput::class,
    processor: InvitationProcessor::class,
)]

Der Processor erhält das validierte DTO und verarbeitet die Geschäftslogik: den Einladungsdatensatz erstellen, die E-Mail über Messenger dispatchen, die passende Antwort zurückgeben. Deine Entity exponiert der API-Schicht niemals Felder wie invitationToken oder expiresAt.

Performance-Muster für APIs unter realer Last

API Platform funktioniert bis zu einigen Hundert gleichzeitigen Nutzern gut out of the box. Darüber hinaus erfordern zwei Bereiche bewusste Aufmerksamkeit.

HTTP-Caching. API Platform sendet standardmäßig korrekte Cache-Control- und Vary-Header. Ein Reverse-Proxy wie Varnish oder Cloudflare davor zu schalten multipliziert die Lesekapazität um Größenordnungen. Das #[ApiResource]-Attribut akzeptiert cacheHeaders für granulare Kontrolle pro Ressource, und die eingebaute Varnish-Integration unterstützt Cache-Invalidierung über Cache-Tags, wenn eine Entity geschrieben wird.

Datenbankabfragen kontrollieren. Das QueryExtension-Interface von Doctrine ist der Ort, an dem du Multi-Tenancy auf Query-Ebene durchsetzt - jeder Collection-Endpunkt wird automatisch mit einer WHERE organisation_id = :current_org-Klausel ergänzt:

final class CurrentOrganisationExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{
    public function applyToCollection(QueryBuilder $qb, QueryNameGeneratorInterface $generator, string $resourceClass, Operation $operation = null, array $context = []): void
    {
        $this->addWhere($qb, $resourceClass);
    }

    private function addWhere(QueryBuilder $qb, string $resourceClass): void
    {
        if (!in_array(BelongsToOrganisation::class, class_implements($resourceClass), true)) {
            return;
        }

        $alias = $qb->getRootAliases()[0];
        $org = $this->security->getUser()?->getOrganisation();
        $qb->andWhere("{$alias}.organisation = :org")->setParameter('org', $org);
    }
}

Ein BelongsToOrganisation-Marker-Interface auf allen mandantenbezogenen Entities zu implementieren und diese eine Extension zu registrieren deckt jeden Collection- und Item-Endpunkt in deiner gesamten API ab. Das ist eines jener Muster, die ein Code-Qualitäts-Audit zu empfehlen wirklich befriedigend machen - weil es Dutzende verstreute WHERE-Klauseln durch eine einzige durchgesetzte Richtlinie ersetzt.

Wann API Platform die falsche Wahl ist

API Platform ist nicht universell die richtige Antwort. Für reine schreibintensive Event-Ingestion-Endpunkte - hochfrequente Webhook-Receiver, Analytics-Erfassung, Bulk-Import-Pipelines - erhöht der Framework-Overhead pro Request die Latenz, die du nicht brauchst. Ein schlanker Symfony-Controller, der validiert, eine Messenger-Message dispatcht und ein 202 zurückgibt, wird API Platform auf diesen Pfaden outperformen.

Ebenso gilt: Wenn deine API-Schicht primär Calls zu externen Services orchestriert anstatt Doctrine-Entities zu lesen und zu schreiben, ist das ressourcenzentrische Modell unpassend. API Platform glänzt, wenn deine API-Oberfläche einigermaßen auf dein Domänenmodell abbildet. Wenn das nicht der Fall ist, ist ein Custom-Software-Entwicklungs-Ansatz mit zweckgebundenen Controllern die pragmatische Wahl.

Die praktische Kalkulation

Für die meisten Symfony-Anwendungen mit einer standardmäßigen CRUD-lastigen API-Oberfläche ist API Platform der richtige Standard. Es eliminiert wochenlangen Boilerplate, hält deine OpenAPI-Dokumentation aktuell und liefert GraphQL gratis, wenn du es brauchst. Die Lernkurve konzentriert sich auf drei Bereiche - eigene State Provider für komplexe Lesevorgänge, DTO-basierte Inputs für komplexe Schreibvorgänge und Query Extensions für Multi-Tenancy - und jeder hat ein klares, wiederholbares Muster, sobald du es einmal gemacht hast.

Teams, die auf API Platform aufbauen, finden auch, dass Code-Reviews konsistenter werden: Es gibt einen kanonischen Weg, einen Filter hinzuzufügen, einen kanonischen Weg, eine operationsbezogene Sicherheitsprüfung hinzuzufügen, einen kanonischen Weg zu paginieren. Diese Konsistenz hat einen kumulativen Wert, wenn das Team wächst.

Wenn deine Symfony-API über den Punkt hinauswächst, an dem manuelle Controller unhandlich werden, ist API Platform eine Investition wert, die es richtig zu evaluieren gilt. Melde dich bei uns unter hello@wolf-tech.io oder besuche wolf-tech.io - wir führen API-Platform-Adoptionsbewertungen für Teams durch, die genau diesen Übergang meistern.