🟡 Inhalte (Things) und Endpoints

Bevor du mit Filtern, Includes oder Paging arbeitest, ist es wichtig zu verstehen, wie dataCycle Inhalte modelliert und wie diese Inhalte über Endpoints bereitgestellt werden.

Dieses Kapitel beschreibt die zwei zentralen Bausteine der API:

Inhalte (Things) – einzelne, strukturierte Datensätze
Endpoints – kontrollierte Sichten, über die Inhalte nach außen ausgeliefert werden

Überblick

In dataCycle gilt ein klares Prinzip:

Inhalte existieren unabhängig – Endpoints bestimmen, was sichtbar ist.

Inhalte werden einmal zentral modelliert und gepflegt
Endpoints definieren welche Inhalte, in welchem Kontext und für wen über die API verfügbar sind

Die API arbeitet immer mit Inhalten, aber nie ohne Endpoints.

Inhalte (Things)

Ein Inhalt ist die kleinste fachliche Einheit in dataCycle.

Typische Inhalte sind zum Beispiel:

Veranstaltungen
Orte / POIs
Touren
Unterkünfte
Medien (Bilder, Videos, Dokumente)
Produkte oder Infrastrukturobjekte

Technisch werden Inhalte in der API als Things bezeichnet.

Eigenschaften eines Inhalts

Jeder Inhalt ist:

eindeutig identifizierbar (UUID über @id)
typisiert (über @type)
strukturiert (klar definierte Attribute)
unabhängig vom Ausgabekanal
mit anderen Inhalten verknüpfbar

Ein Inhalt existiert genau einmal – egal, ob er später:

auf einer Website
in einer App
in einer Karte
oder über eine API

verwendet wird.

Beispiel: Minimaler Inhalt

Ein stark vereinfachtes Beispiel eines Inhalts:

{
  "@id": "8c6a1a1e-3f3a-4b33-8e7a-6b1b9c9c1234",
  "@type": ["Event", "dcls:Veranstaltung"],
  "name": "Sommerkonzert im Park",
  "startDate": "2026-07-12T19:00:00"
}

Wichtig:

@id identifiziert den Inhalt eindeutig
@type beschreibt, was dieser Inhalt fachlich ist
alle weiteren Felder sind Attribute dieses Inhalts

Verknüpfte Inhalte (Relationen)

Inhalte können untereinander verknüpft sein, zum Beispiel:

eine Veranstaltung hat einen Veranstaltungsort
eine Tour hat mehrere Bilder
ein POI gehört zu einer Region

Wichtiges Grundprinzip

👉 Verknüpfte Inhalte werden standardmäßig nur mit @id und @type ausgeliefert. Alle weiteren Attribute müssen explizit über include angefordert werden.

Beispiel: Tour mit Bildern (ohne Include)

"image": [
  {
    "@id": "f38d2202-17a0-4f7a-92db-1ab3d67bb393",
    "@type": [
      "CreativeWork",
      "MediaObject",
      "ImageObject",
      "dcls:Bild"
    ]
  }
]

In diesem Zustand weißt du:

dass es ein Bild gibt
welche ID es hat
welchen Typ es hat

Aber noch nicht:

URL
Titel
Copyright
Bildgrößen

➡️ Diese Informationen bekommst du erst mit include=image.

Dieses Verhalten ist absichtlich so umgesetzt, um:

Payloads klein zu halten
Responses vorhersehbar zu machen
Performance zu sichern

Mehr dazu im Kapitel Relationen & Includes.

Endpoints: Der einzige Weg zur API

Die API von dataCycle stellt keine freien Inhalte bereit.

👉 Alle Inhalte werden ausschließlich über Endpoints ausgeliefert.

Ein Endpoint ist eine vordefinierte, kontrollierte Sicht auf Inhalte und legt fest:

welche Inhalte ausgeliefert werden
nach welchen Regeln (z. B. Filter, Sortierung)
wer Zugriff darauf hat

Wenn ein Inhalt nicht Teil eines Endpoints ist, kann ihn die API nicht liefern – auch dann nicht, wenn er intern existiert.

Inhalte und Endpoints im Zusammenspiel

Inhalte sind die fachliche Wahrheit
Endpoints sind die kontrollierte API-Sicht darauf

Ein Endpoint kann:

viele Inhalte enthalten
sich dynamisch durch Filter befüllen
für unterschiedliche Anwendungsfälle existieren (z. B. Website, App, Partner, Sprache, Region)

Die API selbst bleibt dabei stabil, auch wenn sich interne Inhalte ändern.

Warum diese Trennung wichtig ist

Durch die klare Trennung von:

Inhalt
Endpoint

erreicht dataCycle:

hohe Datenqualität
stabile und planbare APIs
klare Berechtigungen
performante Responses
langfristige Wartbarkeit

Das Frontend entscheidet nicht, was geliefert wird – sondern nur, wie die gelieferten Inhalte dargestellt werden.

Kurz zusammengefasst

Inhalte (Things) sind die kleinste Einheit in dataCycle
Inhalte sind typisiert, strukturiert und eindeutig
Verknüpfte Inhalte liefern standardmäßig nur ID + Typ
Details kommen nur über include
Endpoints sind der einzige Zugriffspunkt der API
Ohne Endpoint → kein API-Zugriff

➡️ Im nächsten Kapitel schauen wir uns an, wie Klassifizierungen Inhalte strukturieren und filterbar machen.