GraphQL
Die lesende GraphQL-Schnittstelle der Content API: Endpunkt, Anmeldung, automatisch erzeugte Abfragen je Collection, Filter, Beziehungen, Grenzen und die Testoberfläche im Browser.
Worum es geht
Neben den REST-Endpunkten bietet die Content API eine lesende GraphQL-Schnittstelle. Das Schema entsteht automatisch aus Ihren Collections: Jede Collection mit API aktiv erhält eigene Abfragen mit typisierten Filtern. Ist das Token auf einzelne Collections beschränkt, enthält das Schema nur diese. Sinnvoll ist GraphQL, wenn Sie in einer Anfrage genau die Felder und Beziehungen holen wollen, die eine Seite braucht.
Endpunkt und Anmeldung
POST https://<ihre-organisation>.scorebase.ch/headless/api/v1/graphql
Authorization: Bearer <token>
Content-Type: application/json
- Das Token braucht die Berechtigung Lesen. Andere Status als
published(z.B. Entwürfe) verlangen zusätzlich Vorschau. - Entwürfe ohne ausdrückliches
status-Argument (ein Eintrag per id, Entwürfe als verknüpfte Einträge) liefert ein Token mit Vorschau nur, wenn die Anfrage?preview=1oder den KopfX-Hcms-Preview: 1trägt. So sieht kein Besucher Ihrer Website Entwürfe. - Die Umgebung folgt dem Token bzw. dem Parameter
?environment=<key>. - Antworten werden nie zwischengespeichert (
no-store). Für häufig abgerufene Seiten ist die REST-Schnittstelle mit ihren Cache-Kopfzeilen oft die bessere Wahl.
Abfragen je Collection
Für eine Collection mit dem Slug blog-posts entstehen:
blogPostsEntries(filter, sort, order, page, limit, locale, status): {
items: [BlogPosts!]
total: Int
page: Int
limit: Int
}
blogPostsEntry(id: ID!): BlogPostsDer Name ergibt sich aus dem Slug in Kamel-Schreibweise. Jedes Objekt enthält die Metafelder id, locale, status, slug, publishedAt, createdAt, updatedAt und alle Datenfelder. Beziehungs- und Medienfelder lösen sich direkt in ihre Zielobjekte auf. Zeigt eine Beziehung auf eine Collection, die das Token nicht sehen darf, liefert das Feld nur die ID(s).
Beispiel: Filtern und Blättern
query {
blogPostsEntries(
filter: { or: [ { featured: { eq: true } }, { price: { lt: 10 } } ] }
sort: "publishedAt"
order: desc
page: 1
limit: 20
) {
total
items {
id
slug
title
author { id name }
heroImage { url width height }
}
}
}Operatoren je Feld: eq, ne, gt, gte, lt, lte, contains, startsWith, in, verknüpfbar mit and und or (Listen von Filtern). Sie entsprechen dem JSON-Filter der REST-Schnittstelle.
Testoberfläche im Browser
Öffnen Sie die Adresse des Endpunkts im Browser (GET ohne Abfrage). Es erscheint eine Testoberfläche, in der Sie Abfragen schreiben und das Schema durchsuchen. Tragen Sie dort im Bereich für Kopfzeilen ein:
{ "Authorization": "Bearer <token>" }Grenzen
| Grenze | Wert |
|---|---|
| Verschachtelungstiefe einer Abfrage | 8 |
| Aliase je Abfrage | 15 |
| Umfang einer Abfrage | 2000 Bausteine (Tokens) |
| Einträge je Liste | höchstens 100 (limit) |
Zu umfangreiche Abfragen werden abgewiesen. Schreiben geht über GraphQL nicht – nutzen Sie dafür die REST-Endpunkte mit den Berechtigungen Schreiben und Veröffentlichen, siehe Content API.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| Eine Collection fehlt im Schema | API aktiv ist aus, die Collection steht nicht in der Collection-Beschränkung des Tokens, oder das Token zeigt auf eine andere Umgebung | Schalter, Beschränkung und Umgebung des Tokens prüfen |
| Fehler zu Tiefe oder Umfang | Abfrage überschreitet die Grenzen | Abfrage aufteilen oder weniger tief verschachteln |
Keine Entwürfe trotz status: "draft" |
Token ohne Vorschau | Token mit Berechtigung Vorschau verwenden |
Ein Entwurf per id liefert null |
Das Signal ?preview=1 bzw. X-Hcms-Preview: 1 fehlt |
Signal mitschicken, nur im Entwurfsmodus |