Content Negotiation in REST-APIs jenseits von JSON

1. Wie Content Negotiation über den Accept-Header funktioniert

Der Accept-Header, den ein Client bei jeder HTTP-Anfrage mitschickt, teilt dem Server mit, welche Medientypen der Client verarbeiten kann und in welcher Präferenzreihenfolge, ausgedrückt über Quality-Werte wie application/json;q=0.9, text/csv;q=0.5. Ein Server, der Content Negotiation unterstützt, wählt basierend auf diesem Header das passende Antwortformat, statt für jede Ressource nur ein einziges, fest kodiertes Format anzubieten.

Dieser Mechanismus ist Teil des HTTP-Standards selbst (RFC 9110) und unabhängig vom konkreten Framework, wodurch sich Content Negotiation grundsätzlich in jede REST-API integrieren lässt, unabhängig davon, ob sie mit Symfony, Express oder einem anderen Framework gebaut ist.

Neben dem Accept-Header für das Antwortformat existieren mit Accept-Language und Accept-Charset verwandte Header für Sprach- und Zeichensatz-Negotiation, die demselben Grundprinzip folgen, in diesem Artikel aber bewusst außen vor bleiben, weil der Fokus hier auf der Repräsentationsform der Daten liegt, nicht auf Sprache oder Kodierung.

2. Content Negotiation mit dem Symfony Serializer umsetzen

Symfonys Serializer-Komponente unterstützt von Haus aus mehrere Encoder (JsonEncoder, XmlEncoder, CsvEncoder), die alle auf demselben normalisierten Datenmodell arbeiten, sodass eine einzige Controller-Aktion je nach angefragtem Format den passenden Encoder auswählen kann, ohne die Geschäftslogik zu duplizieren. Die Formaterkennung selbst kann über einen dedizierten Content-Negotiation-Listener erfolgen, der den Accept-Header parst und das Ergebnis in das Request-Attribut _format schreibt.

Wichtig ist, den negotiation-Prozess klar von der reinen Serialisierung zu trennen: Die Negotiation entscheidet WELCHES Format verwendet wird, der Serializer WIE die Daten in dieses Format überführt werden. Diese Trennung hält den Controller-Code unabhängig vom konkreten Ausgabeformat.

Ein zusätzlicher Vorteil dieser Trennung zeigt sich beim Hinzufügen neuer Formate: Ein neuer Encoder lässt sich als eigenständiger Service registrieren, ohne bestehende Controller-Aktionen anzufassen, solange die Negotiation-Schicht den neuen Medientyp kennt und korrekt auf den passenden Encoder abbildet.

<?php
declare(strict_types=1);

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Serializer\SerializerInterface;

final class OrderExportController
{
    private const SUPPORTED_FORMATS = [
        'application/json' => 'json',
        'text/csv' => 'csv',
        'application/xml' => 'xml',
    ];

    public function __construct(private readonly SerializerInterface $serializer) {}

    public function export(Request $request, array $orders): Response
    {
        $accept = $request->headers->get('Accept', 'application/json');
        $format = self::SUPPORTED_FORMATS[$accept] ?? 'json';

        $content = $this->serializer->serialize($orders, $format);
        $contentType = array_search($format, array_flip(self::SUPPORTED_FORMATS));

        return new Response($content, 200, ['Content-Type' => $contentType]);
    }
}

3. CSV als praktisches Exportformat für Business-Nutzer

Ein häufiger, praktischer Anwendungsfall für Content Negotiation ist ein CSV-Export derselben Ressource, die auch als JSON-API dient, etwa für Business-Nutzer, die Bestelldaten in Excel weiterverarbeiten wollen, ohne eine separate Export-Funktion pflegen zu müssen. Statt eines eigenen /export/csv-Endpoints mit dupliziertem Query- und Filterlogik reicht ein Accept: text/csv auf dem bestehenden Listen-Endpoint.

Diese Wiederverwendung reduziert nicht nur Code-Duplikation, sondern hält auch Filter-, Sortier- und Paginierungsparameter konsistent zwischen den Formaten, weil dieselbe zugrundeliegende Query-Logik verwendet wird. Ein Nutzer kann exakt dieselbe gefilterte Ansicht sowohl als JSON in der eigenen Anwendung als auch als CSV zum Download erhalten.

Für sehr große Exporte lohnt sich zusätzlich, den CSV-Pfad mit Streaming statt vollständiger In-Memory-Aggregation zu implementieren, damit auch Exporte mit hunderttausenden Zeilen nicht den verfügbaren Arbeitsspeicher des PHP-Prozesses sprengen, bevor die erste Zeile überhaupt an den Client gesendet wurde.

4. PDF und andere Binärformate über Content Negotiation ausliefern

Binärformate wie PDF passen konzeptionell schwerer in den Serializer-Ansatz, weil sie kein einfaches Daten-zu-Format-Mapping sind, sondern eine eigene Rendering-Logik benötigen (etwa über eine Bibliothek wie Dompdf oder mPDF). Trotzdem lässt sich Accept: application/pdf denselben Content-Negotiation-Mechanismus nutzen, indem der Controller bei erkanntem PDF-Wunsch auf einen separaten Rendering-Pfad verzweigt, statt den generischen Serializer zu bemühen.

Diese hybride Behandlung, einheitliche Negotiation-Logik für die Formaterkennung, aber getrennte Rendering-Pfade für strukturierte und binäre Formate, ist in der Praxis üblich und pragmatisch, solange die Content-Negotiation-Schicht selbst konsistent für alle Formate bleibt.

5. Fallback-Strategie bei nicht unterstützten Formaten

Fragt ein Client ein Format an, das die API nicht unterstützt, etwa Accept: application/yaml, sollte der Server nicht stillschweigend auf JSON zurückfallen, sondern mit HTTP 406 Not Acceptable antworten, um dem Client explizit mitzuteilen, dass sein Wunschformat nicht verfügbar ist. Der Response-Body sollte idealerweise die tatsächlich unterstützten Formate auflisten, damit der Client seine Anfrage entsprechend anpassen kann.

Ein stiller Fallback auf JSON mag kurzfristig bequemer wirken, versteckt aber echte Integrationsfehler und führt dazu, dass ein Client möglicherweise über lange Zeit fälschlich annimmt, sein gewünschtes Format werde unterstützt, obwohl er tatsächlich immer JSON zurückbekommt und diesen Unterschied erst bei einer manuellen Prüfung bemerkt.

6. Format-Query-Parameter als pragmatische Alternative

In der Praxis nutzen viele APIs zusätzlich zum Accept-Header einen expliziten Query-Parameter wie ?format=csv, weil sich Accept-Header in Browser-URLs nicht direkt setzen lassen und ein Nutzer, der einen CSV-Export-Link direkt anklicken möchte, keinen HTTP-Client zur Hand hat, der Header manipuliert. Diese Kombination ist kein Widerspruch zur reinen HTTP-Content-Negotiation, sondern eine pragmatische Ergänzung für direkt anklickbare Links.

Wichtig ist, klare Prioritätsregeln zu definieren, falls beide Mechanismen gleichzeitig genutzt werden: Ein expliziter Query-Parameter sollte den Accept-Header überschreiben können, da er eine bewusstere, direktere Nutzerabsicht ausdrückt als ein möglicherweise vom Browser automatisch gesetzter Accept-Header.

7. Unterschiedliche Datenmodelle pro Format vermeiden

Eine Falle bei Content Negotiation ist, dass unterschiedliche Formate mit der Zeit unterschiedliche, inkonsistente Feldmengen ausliefern, etwa weil das CSV-Format aus praktischen Gründen weniger verschachtelte Felder abbildet als JSON. Diese Inkonsistenz überrascht Clients, die zwischen Formaten wechseln, und sollte durch ein einheitliches, formatunabhängiges Datenmodell vermieden werden, aus dem alle Formate abgeleitet werden.

Wo verschachtelte Strukturen in einem flachen Format wie CSV nicht sinnvoll abbildbar sind, sollte diese Einschränkung explizit dokumentiert werden, statt stillschweigend Felder wegzulassen, damit Nutzer des CSV-Exports verstehen, warum bestimmte Informationen dort fehlen, die im JSON-Format vorhanden sind.

Ein pragmatischer Kompromiss für verschachtelte Daten in CSV ist, verschachtelte Objekte als abgeflachte Spalten mit Punkt-Notation abzubilden (etwa customer.address.city), statt sie komplett wegzulassen, solange die Verschachtelungstiefe überschaubar bleibt und die resultierende Spaltenanzahl für Business-Nutzer noch handhabbar ist.

8. Caching und der Vary-Header bei mehreren Formaten

Sobald eine URL je nach Accept-Header unterschiedliche Inhalte liefert, muss jeder zwischengeschaltete Cache (Reverse Proxy, CDN, Browser-Cache) wissen, dass die Antwort vom Accept-Header abhängt, statt eine einzige gecachte Version für alle Clients auszuliefern. Der Vary-Header mit dem Wert Accept signalisiert genau das und weist Caches an, separate Cache-Einträge pro angefragtem Format zu führen.

Wird dieser Header vergessen, kann es zu einem subtilen, schwer zu diagnostizierenden Fehler kommen, bei dem ein Client, der als Erster eine URL mit Accept: text/csv anfragt, versehentlich die CSV-Antwort in den gemeinsamen Cache schreibt, und nachfolgende Clients, die eigentlich JSON wollten, ebenfalls die CSV-Antwort ausgeliefert bekommen. Der Vary-Header ist deshalb bei Content Negotiation mit aktivem Caching praktisch zwingend erforderlich.

Manche Reverse-Proxy-Konfigurationen unterstützen den Vary-Header nur eingeschränkt oder cachen standardmäßig ausschließlich basierend auf der URL, weshalb sich ein expliziter Test lohnt, ob die tatsächlich eingesetzte Caching-Infrastruktur den Vary-Header korrekt respektiert, bevor Content Negotiation produktiv hinter einem Cache betrieben wird.

9. Content-Negotiation-Formate im Überblick

Die folgende Tabelle vergleicht die typischen Einsatzszenarien der gängigsten Formate.

10. Zusammenfassung

11. FAQ: Content Negotiation: Das Wichtigste auf einen Blick