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. 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. - 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.
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, oder das Token zeigt auf eine andere Umgebung | Schalter 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 |