🟡 Endpoints verstehen

Kurz erklärt

Ein Endpoint ist in dataCycle eine vordefinierte Sicht auf Daten.

Du kannst ihn dir vorstellen als:

eine Inhaltssammlung oder
eine gespeicherte Suche

Über die API rufst du in der Regel nicht alle Inhalte einer Instanz ab, sondern immer genau die Inhalte, die ein Endpoint definiert.

➡️ Deshalb brauchst du für die meisten API-Abfragen eine Endpoint-ID oder einen Endpoint-Slug.

Warum gibt es Endpoints?

Endpoints lösen drei zentrale Anforderungen:

Kontrolle & Sicherheit

Nicht jeder API-Zugriff soll alle Inhalte sehen. Ein Endpoint definiert explizit, welche Inhalte ausgeliefert werden dürfen.

Stabilität für Integrationen

Websites, Apps oder Partner-Schnittstellen benötigen eine stabile Datenquelle. Ein Endpoint kann so konfiguriert werden, dass er dauerhaft genau die Inhalte liefert, die ein Frontend erwartet – unabhängig von internen Änderungen.

Performance

Statt sehr großer Datenmengen liefert ein Endpoint nur eine relevante Teilmenge und kann serverseitig optimiert werden (Filter, Sortierung, Indizes).

Statische und dynamische Endpoints

In dataCycle gibt es zwei Arten von Endpoints. Beide werden identisch über die API angesprochen, unterscheiden sich aber in ihrer Logik.

Statische Endpoints (Inhaltssammlungen)

Statische Endpoints enthalten eine manuell gepflegte Auswahl von Inhalten.

Typische Einsatzfälle:

kuratierte Inhalte für Start- oder Landingpages
redaktionelle Empfehlungen
bewusst geprüfte oder eingeschränkte Datensätze

➡️ Die Inhalte ändern sich nur, wenn sie redaktionell angepasst werden.

Dynamische Endpoints (gespeicherte Suchen)

Dynamische Endpoints basieren auf Filterkriterien und werden automatisch befüllt.

Typische Kriterien sind z. B.:

Klassifizierungen
Zeiträume (z. B. zukünftige Veranstaltungen)
Regionen oder Geo-Filter
Kombinationen mehrerer Filter

➡️ Die Inhalte aktualisieren sich automatisch, sobald neue passende Daten vorhanden sind oder sich bestehende Inhalte ändern.

Einheitlicher Zugriff über die API

Unabhängig davon, ob ein Endpoint statisch oder dynamisch ist, gilt:

beide werden über dasselbe URL-Schema angesprochen /api/v4/endpoints/{ENDPOINT_ID | ENDPOINT_SLUG}
beide liefern dieselbe Response-Struktur
für Konsument:innen der API ist der Unterschied nicht relevant

➡️ Die Logik liegt im Endpoint – nicht im Frontend.

ID oder Slug – was ist der Unterschied?

Ein Endpoint kann auf zwei Arten referenziert werden:

ID (UUID) – technisch eindeutig Beispiel: df40c1dd-d6c2-4662-9245-265233b9d0c1
Slug – sprechender Name, gut lesbar Beispiel: zukuenftige-veranstaltungen

Welche Variante du verwendest, ist meist egal. Wichtig ist nur: Der Endpoint muss existieren und du brauchst Zugriff darauf.

Endpoint aufrufen (Minimalbeispiel)

curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  "{BASE_URL}/api/v4/endpoints/{ENDPOINT}"

Typische Missverständnisse

„Ich habe einen Token – warum sehe ich trotzdem nichts?“

Ein Token bedeutet nicht automatisch Zugriff auf alle Inhalte. Mögliche Ursachen:

kein Zugriff auf diesen Endpoint (401 / 403)
Endpoint existiert, enthält aber aktuell keine Inhalte
falsche Endpoint-ID oder falscher Slug

„Warum gibt es mehrere Endpoints für ähnliche Inhalte?“

Das ist normal. Häufig gibt es z. B.:

einen Endpoint für Websites
einen Endpoint für Apps
einen Endpoint für Partner
Endpoints pro Sprache, Region oder Use Case

Nächste Schritte

Paging – große Endpoints sauber durchblättern
Suche & Volltext (filter[q])
Filtern über Klassifizierungen