Skip to content
Datacycle Logo Docs

🟡 Payload schlank halten

Worum geht’s hier?

Section titled “Worum geht’s hier?”

dataCycle ist dafür ausgelegt, komplexe und stark vernetzte Daten zu verwalten. Gleichzeitig sollen APIs schnell, stabil und effizient bleiben – besonders für Websites, Apps und Widgets.

Deshalb liefert die dataCycle API nicht automatisch alle verknüpften Inhalte und Attribute aus.

Stattdessen steuerst du selbst:

  • welche verknüpften Inhalte du brauchst → include
  • welche Attribute tatsächlich übertragen werden → fields

➡️ Ziel: kleine Payloads, bessere Performance, klare Verantwortung im Frontend

Warum werden verknüpfte Inhalte nicht automatisch ausgeliefert?

Section titled “Warum werden verknüpfte Inhalte nicht automatisch ausgeliefert?”

Viele Inhalte in dataCycle sind stark miteinander verbunden, z. B.:

  • ein Event mit:

    • Veranstaltungsort
    • Bildern
    • Kategorien
    • Ansprechpartner:innen

  • eine Tour mit:

    • POIs
    • Schutzgebieten
    • Medien
    • Relationen zu Regionen

Würde die API immer alles automatisch mitliefern, hätte das Nachteile:

  • sehr große Responses
  • unnötige Datenübertragung
  • schlechtere Performance
  • wenig Kontrolle im Frontend

➡️ Deshalb gilt in dataCycle bewusst:

Verknüpfte Inhalte werden nur ausgeliefert, wenn sie explizit angefordert werden.

include: Verknüpfte Inhalte gezielt mitladen

Section titled “include: Verknüpfte Inhalte gezielt mitladen”

Mit dem Parameter include kannst du festlegen, welche Relationen zusätzlich aufgelöst werden sollen.

Beispiel: Inhalte ohne include

Section titled “Beispiel: Inhalte ohne include”
Terminal window
curl -s \
-H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}"

➡️ Ergebnis:

  • Hauptinhalte (@graph)
  • Referenzen auf verknüpfte Inhalte (IDs / Links)
  • keine aufgelösten Objekte

Beispiel: Inhalte mit include

Section titled “Beispiel: Inhalte mit include”
Terminal window
curl -s \
-H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?include=images,location"

➡️ Ergebnis:

  • Hauptinhalte

  • zusätzlich:

    • Bilder
    • Orte

  • alle enthaltenen Objekte sauber im Response verknüpft

💡 include ist besonders wichtig für:

  • Detailseiten
  • Karten
  • Widgets mit Zusatzinfos
  • API-Consumer, die nicht mehrere Requests machen wollen

fields: Nur die Attribute abrufen, die du wirklich brauchst

Section titled “fields: Nur die Attribute abrufen, die du wirklich brauchst”

Nicht jeder Ausgabekanal braucht alle Attribute eines Inhalts.

Beispiel:

  • Listenansicht:

    • Name
    • Vorschaubild

  • Detailseite:

    • Beschreibung
    • Medien
    • Relationen
    • Metadaten

Mit fields kannst du die Payload gezielt reduzieren.

Beispiel: Listenansicht mit minimalen Feldern

Section titled “Beispiel: Listenansicht mit minimalen Feldern”
Terminal window
curl -s \
-H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?fields=name,image"

➡️ Ergebnis:

  • nur name und image
  • keine großen Textfelder
  • keine unnötigen Metadaten

💡 Für Listen, Teaser, Slider und Übersichten ist das der empfohlene Standard.

include und fields kombinieren

Section titled “include und fields kombinieren”

Die volle Stärke entfaltet sich, wenn du beide Parameter kombinierst.

Beispiel: Liste mit Bildern, aber schlanker Payload

Section titled “Beispiel: Liste mit Bildern, aber schlanker Payload”
Terminal window
curl -s \
-H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?include=images&fields=name,image"

➡️ Ergebnis:

  • Hauptinhalt: nur Name + Bild-Referenz
  • Bilder: nur URL + Alt-Text
  • keine überflüssigen Attribute

Typische Einsatzmuster

Section titled “Typische Einsatzmuster”

🔹 Listen & Übersichten

Section titled “🔹 Listen & Übersichten”
  • fields → sehr restriktiv
  • include → meist nur Medien

🔹 Detailseiten

Section titled “🔹 Detailseiten”
  • include → gezielt (Relationen, Medien, Orte)
  • fields → optional, je nach Komplexität

🔹 Widgets & Karten

Section titled “🔹 Widgets & Karten”
  • kleine Payloads
  • oft nur Geodaten + Titel
  • fields extrem wichtig

Best Practices

Section titled “Best Practices”

  • ❌ Nicht: Alles laden und im Frontend ignorieren

  • ✅ Besser: Nur das anfordern, was wirklich angezeigt wird

  • ❌ Nicht: Große verschachtelte Responses für einfache Listen

  • ✅ Besser: fields für jede View optimieren

  • ✅ Frontend entscheidet, was es braucht

  • ✅ Backend bleibt generisch und leistungsfähig

Nächste Schritte

Section titled “Nächste Schritte”
  • Endpoints verstehen
  • Paging (große Datenmengen sauber abrufen)
  • Filtern: Klassifizierungen
  • Referenz: include & fields im Detail

💡 Kurz gesagt:

include bestimmt welche Inhalte, fields bestimmt wie viel davon.

© dataCycle ✨