🟡 Schnellstart

In diesem Schnellstart führst du eine funktionierende Anfrage an eine dataCycle-Instanz aus und verstehst dabei die wichtigsten Grundprinzipien der API.

👉 Ziel: Am Ende hast du echtes JSON aus deiner Instanz vor dir und weißt:

wie Requests grundsätzlich aufgebaut sind
warum Endpoints zentral sind
was du prüfst, wenn „nichts zurückkommt“

Was du brauchst

Für alle Beispiele in diesem Schnellstart gelten dieselben Platzhalter:

{BASE_URL} z. B. https://hub.datacycle.cloud oder https://<deine-instanz>
{ENDPOINT} ID oder Slug eines Endpoints (vorkonfigurierte Datensammlung)
{TOKEN} API-Token (Bearer Token)

Wichtigstes Grundprinzip (bitte einmal lesen)

Die dataCycle API liefert Inhalte ausschließlich über Endpoints.

Ein Endpoint ist eine vorkonfigurierte Sammlung von Inhalten. Wenn ein Inhalt nicht im Endpoint liegt, kann ihn die API nicht liefern – egal wie korrekt dein Request ist.

👉 Deshalb:

immer zuerst ohne Filter testen
Fehler fast immer zuerst beim Endpoint suchen

1️⃣ Erste Anfrage (ohne Filter)

Starte immer mit der minimalen Anfrage, um zu prüfen:

Base URL stimmt
Token funktioniert
Endpoint liefert grundsätzlich Daten

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}"

Was du prüfen solltest:

Kommt HTTP 200 zurück?
Gibt es eine Liste von Einträgen im Attribut @graph?
Wenn leer → siehe Abschnitt Troubleshooting

2️⃣ Paging – mehr oder weniger Ergebnisse

Endpoints liefern standardmäßig paginierte Ergebnisse.

Beispiel: 10 Einträge pro Seite

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}?page[size]=10"

Beispiel: nächste Seite

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}?page[size]=10&page[number]=2"

3️⃣ Payload schlank halten (fields)

Für Frontends und Tests ist es sinnvoll, nur benötigte Felder zu laden.

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}?fields=id,name,image"

👉 Weniger Payload = schnellere Responses & einfacheres Debugging.

4️⃣ Verknüpfte Daten laden (include)

Verknüpfte Inhalte (z. B. Medien, Relationen) werden nicht automatisch geladen.

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}?include=image,author"

👉 include bestimmt was zusätzlich geladen wird 👉 fields bestimmt wie viel davon

5️⃣ Erster Filter – Volltextsuche

curl -sS \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT ID oder SLUG}?filter[q]=berg"

6️⃣ Häufige Fehlerbilder (Troubleshooting)

„200 OK, aber leer“

Fast immer einer dieser Gründe:

falscher {ENDPOINT} (ID / Slug)
Filter zu restriktiv
Daten existieren, sind aber nicht im Endpoint

👉 Test: alle Parameter und Filter entfernen, nur endpoints/... lassen.

401 Unauthorized

Token fehlt, ist falsch oder abgelaufen
falscher Authorization-Header (Bearer fehlt)

403 Forbidden

Token ist gültig, aber nicht berechtigt, diesen Endpoint zu lesen

404 Not Found

falsche Base URL oder falsche API-Version

7️⃣ Nächste sinnvolle Schritte

Wenn der Schnellstart funktioniert, sind typische nächste Themen:

Filter kombinieren (Text + Zeit + Geo)
Sortierung
stabile Integrationen (Retries, Fehlercodes)
Response-Struktur im Detail verstehen