🟡 Relationen, Includes und Fields

title: Relationen, Includes und Fields

Bevor du mit komplexeren API-Abfragen arbeitest, ist es wichtig zu verstehen, wie Relationen zwischen Inhalten funktionieren und wie du sie gezielt über include und fields auflösen kannst.

Dieses Kapitel erklärt das Prinzip und zeigt typische Beispiele aus der Praxis.

Überblick

In dataCycle sind Inhalte (Things) explizit miteinander verknüpft. Diese Verknüpfungen werden nicht automatisch aufgelöst, sondern nur dann mitgeliefert, wenn du sie ausdrücklich anforderst.

Das sorgt für:

kleine Payloads
vorhersehbare Responses
gute Performance

Was sind Relationen?

Eine Relation ist eine Referenz von einem Inhalt auf einen anderen Inhalt.

Typische Beispiele:

Eine Veranstaltung hat einen Ort
Eine Tour hat mehrere Bilder
Ein POI gehört zu einer Region

Technisch wird dabei zunächst nur auf den Ziel-Inhalt verwiesen.

Relationen ohne `include`

Standardmäßig liefert die API bei Relationen nur ID und Typ des verknüpften Inhalts.

{
  "@id": "e7c4c9e3-9c4a-4e2d-b7c1-6a4f1a9d1234",
  "@type": ["Event", "dcls:Veranstaltung"],
  "name": "Open-Air-Konzert",
  "location": {
    "@id": "a12f8b44-3d9a-4b1c-9d77-5a8f12345678",
    "@type": ["Place", "dcls:Ort"]
  }
}

In diesem Zustand weißt du:

dass es einen Ort gibt
welche ID er hat
welchen Typ er hat

Du weißt noch nicht:

Name des Ortes
Adresse
Geo-Koordinaten
weitere Attribute

Relationen mit `include`

Um die verknüpften Inhalte vollständig zu erhalten, musst du sie explizit anfordern.

Beispiel:

GET /api/v4/endpoints/{ENDPOINT}?include=location

Die Response enthält dann zusätzlich den vollständigen Ort:

{
  "@id": "e7c4c9e3-9c4a-4e2d-b7c1-6a4f1a9d1234",
  "@type": ["Event", "dcls:Veranstaltung"],
  "name": "Open-Air-Konzert",
  "location": {
    "@id": "a12f8b44-3d9a-4b1c-9d77-5a8f12345678",
    "@type": ["Place", "dcls:Ort"],
    "name": "Stadtpark",
    "address": "Musterstraße 1",
    "geo": {
      "lat": 48.137,
      "lon": 11.575
    }
  }
}

Mehrere Includes

Du kannst mehrere Relationen gleichzeitig auflösen:

GET /api/v4/endpoints/{ENDPOINT}?include=location,image,organizer

Wichtig dabei:

Nur explizit genannte Relationen werden aufgelöst
Nicht vorhandene Relationen werden ignoriert
Zu viele Includes können die Payload stark vergrößern

Includes mit `fields` kombinieren

Um die Response weiter zu optimieren, kannst du include mit fields kombinieren.

Beispiel:

GET /api/v4/endpoints/{ENDPOINT}
  ?include=location
  &fields[location]=name,geo

Ergebnis:

Die Relation location wird aufgelöst
Es werden nur die angegebenen Felder ausgeliefert

Das ist besonders sinnvoll bei:

großen Relationen
mobilen Anwendungen
performancekritischen Frontends

Wichtiges Grundprinzip

Was du nicht includest, bekommst du nicht.

Dieses Prinzip ist bewusst so gewählt und gilt überall in der API.

Vorteile:

volle Kontrolle über die Datenmenge
keine versteckten Abhängigkeiten
stabile und wartbare Integrationen

Best Practices

Includes sparsam einsetzen
Nur das includen, was das Frontend wirklich braucht
Große Relationen (z. B. viele Bilder) gezielt testen
include mit fields kombinieren, um Payloads weiter zu reduzieren

Kurz zusammengefasst

Relationen verknüpfen Inhalte miteinander
Standardmäßig werden nur ID + Typ ausgeliefert
Vollständige Daten kommen nur über include
fields hilft, Responses weiter zu verschlanken
Alles ist explizit – für Performance und Stabilität

➡️ Im nächsten Kapitel schauen wir uns an, wie Paging und Sortierung funktionieren.