sylius-api-catalog — der Katalog und der Weg dorthin.

Ein Katalog, den niemand findet, ist kein Discovery-Mechanismus

Katalog und Link-Header stecken bewusst in einem Paket. RFC 9727 definiert in §3 den Link-Header als den Weg, auf dem ein Client den Katalog überhaupt entdeckt — es sind dieselben Daten in zwei Serialisierungen, nicht zwei Funktionen. Auf zwei Pakete verteilt, wäre jede der beiden Hälften einzeln installierbar: ein Katalog, auf den nichts zeigt, oder Header, die auf nichts zeigen. Beide Fälle sehen bei einer Prüfung von außen aus wie eine kaputte Implementierung.

Der Katalog listet, was die installierten Bundles anmelden, ohne sie zu kennen. Damit gibt es keine zentrale Liste, die bei jedem neuen Endpunkt nachgezogen werden müsste — und keine Kopplung in die falsche Richtung, bei der das generische Katalog-Paket seine eigenen Abnehmer hart referenzieren müsste. Ein Bundle, das später dazukommt, erscheint im Katalog, ohne dass dieses Paket geändert wird.

Link-Header werden angehängt, nie ersetzt. Sylius und API Platform setzen eigene Link-Header, unter anderem für Hydra und Preload-Hinweise. Ein überschreibender Header ist ein Fehler, der die Discovery erst herstellt und dabei eine andere zerstört — und der in einem isolierten Test nicht auffällt, weil dort schlicht keine anderen Header da sind.