REST-API

Das Frontend braucht die zehn neuesten veröffentlichten Beiträge einer Kategorie, mit aufgelöstem Autor und ohne den Body. In RustyCMS ist das ein GET mit vier Parametern. Jede Collection, die du als Schema anlegst, hat sofort ihre Endpoints — Liste und Einzeleintrag — und die OpenAPI-Spec kennt sie ebenfalls.

Filter, die in die URL passen

GET /api/content/post?category=energie&_status=published
GET /api/content/product?category_in=electronics,tools&price_min=50&subtitle_exists=true
GET /api/content/post?_or=category:energie,category:netz&featured=true
GET /api/content/post?autor.name=Meier

Exakt, _prefix, _contains, _min/_max, _in, _ne, _exists. Filter werden mit UND verknüpft, _or ergänzt genau einen ODER-Block. Ein Punkt im Feldnamen greift in verschachtelte Objekte, Arrays passen, sobald ein Element passt. Das ist absichtlich keine Query-Sprache: Die Grammatik passt in eine Tabelle, und jeder Operator verhält sich in allen Stores gleich — Datei, SQLite, Postgres.

Sortieren, blättern, nur das Nötige laden

_sort und _order sortieren, ein Schema kann eine Standardsortierung vorgeben. Blättern geht seitenweise (_page/_per_page) oder per _limit/_offset; die Antwort enthält total und total_pages, der Header X-Total-Count das Gesamtergebnis. _resolve bettet referenzierte Einträge ein, _depth begrenzt die Tiefe, Zyklen werden erkannt. Eine fehlende Referenz wird als _missing markiert statt den ganzen Request zu kippen. _fields=title,author.name liefert nur, was das Frontend rendert.

Facetten, die ein Versprechen halten

GET /api/content/post/_facets?by=category,featured&_status=published
# → { "category": { "energie": 12, "netz": 7 }, "featured": { "true": 4, "false": 15 } }

Facetten zählen mit exakt den Filtern der Liste. Die Zusage: Die Zahl neben einem Wert ist das total derselben Liste mit diesem Filter zusätzlich. Eine Facette darf deshalb ein Link sein — der Nutzer klickt auf „energie (12)” und bekommt zwölf Treffer.

Weniger Roundtrips, weniger Bytes

Einzeleinträge tragen ein ETag; schickt der Client If-None-Match, antwortet die API mit 304 ohne Body. Der Batch-Endpoint bündelt bis zu 50 Lookups in einem POST, jeder mit eigenem Status und eigener Rechteprüfung — eine Seite mit Header, Footer und drei Teasern ist ein Request. Validierungsfehler kommen mit Feldbezug zurück: „Field is required”, „Value does not match pattern”, „Value must be unique” — nicht als 500.

Eine Spec, die deine Collections kennt

Die OpenAPI-Spec liegt unter /api-docs/openapi.json, Swagger UI unter /swagger-ui. Sie wird zur Laufzeit gebaut: Die statischen Endpoints plus ein Pfadsatz pro Collection aus deinen Schemas. Legst du ein neues Schema an, taucht es in der Spec auf. Daraus lassen sich mit einem üblichen Generator TypeScript-Typen ableiten — das Frontend weiß beim Kompilieren, welche Felder ein post hat.