Datenschnittstelle Übersicht

🚀 Was ist die dataCycle-API?

Die dataCycle-API ist wie eine Tür, durch die du Daten aus dem dataCycle-System holen kannst. Du kannst damit zum Beispiel Listen von Artikeln, Bildern oder Kategorien abfragen – ganz automatisch, ohne die Oberfläche zu benutzen.

Das funktioniert mit sogenannten Endpunkten (englisch: Endpoints). Ein Endpunkt ist einfach eine Internet-Adresse, die du aufrufen kannst, um bestimmte Daten zu bekommen.

🗂 Welche Arten von Daten gibt es

Klassifizierungen: Das sind Kategorien oder Themenbäume, mit denen Inhalte sortiert werden (z.B. “Sport”, “Kultur”, “Technik”).
Inhalte: Das sind die eigentlichen Daten wie Artikel, Veranstaltungen, Bilder, Orte usw.

🔑 Was brauche ich, um loszulegen?

Die Internet-Adresse (URL) deiner dataCycle-Installation, z.B. https://meinserver/datacycle
Einen Zugang: Entweder bist du schon im System eingeloggt, oder du bekommst einen Token (eine Art Passwort für Programme)

Tipp: Du kannst die API im Browser testen, mit dem Programm curl (Kommandozeile) oder mit Tools wie
Postman
.

📋 Beispiel: Kategorien abfragen

Um alle Kategorien (Klassifizierungen) zu sehen, rufe einfach diese Adresse im Browser auf:

https://meinserver/datacycle/api/v4/concept_schemes

Falls du einen Token brauchst, hänge ihn so an:

https://meinserver/datacycle/api/v4/concept_schemes?token=DEIN_TOKEN

Oder mit curl (ersetze DEIN_TOKEN durch deinen echten Token):

Terminal window
```bash
</pre>
</section>

<section>
<h2>📰 Beispiel: Inhalte abfragen</h2>
<p>Inhalte wie Artikel oder Bilder bekommst du über eigene Endpunkte. Zum Beispiel:</p>
<pre>
<code>https://meinserver/datacycle/api/v4/articles?token=DEIN_TOKEN</code>
</pre>
<p>
Welche Endpunkte es für Inhalte gibt, hängt davon ab, was im System freigegeben wurde. Frag ggf. bei deinem Admin
nach.
</p>
</section>

<section>
<h2>📦 Wie sehen die Daten aus?</h2>
<p>
Die Daten kommen im <strong>JSON-LD-Format</strong>. Das ist eine Art, Daten für Computer verständlich und gleichzeitig für Menschen lesbar zu machen.
</p>
<p>Ein typisches Beispiel:</p>
<pre>
```json
{
"@context": {},
"@graph": [],
"meta": {
"total": 123,
"pages": 5
},
"links": {
"next": "/api/...",
"prev": "/api/..."
}
}

@context: Infos zum Datenformat
@graph: Hier stehen die eigentlichen Daten (z.B. die Liste der Artikel)
meta: Zusatzinfos, z.B. wie viele Einträge es insgesamt gibt
links: Links zum Weiterblättern (nächste/vorherige Seite)

🔄 Wie blättere ich durch viele Ergebnisse?

Wenn es viele Einträge gibt, bekommst du sie seitenweise. Mit diesen Parametern steuerst du das:

page[size]: Wie viele Einträge pro Seite?
page[number]: Welche Seite?

Beispiel:

https://meinserver/datacycle/api/v4/concept_schemes?page[size]=10&page[number]=2&token=DEIN_TOKEN

Die Antwort enthält dann auch, wie viele Seiten es insgesamt gibt und wie du zur nächsten/vorherigen Seite kommst:


{
  "meta": {
    "total": 71,
    "pages": 3
  },
  "links": {
    "prev": "/api/v4/concept_schemes?page[size]=25&page[number]=1",
    "next": "/api/v4/concept_schemes?page[size]=25&page[number]=3"
  }
}

🔐 Wie funktioniert die Anmeldung?

Wenn du im Browser eingeloggt bist, brauchst du oft nichts weiter tun.
Sonst brauchst du einen Token (frag deinen Admin).
Du kannst den Token entweder als ?token=DEIN_TOKEN an die URL hängen oder als Bearer-Token im Header schicken:

curl —url https://meinserver/datacycle/api/v4/concept_schemes \ —header ‘Authorization: Bearer DEIN_TOKEN’

Auch Anmeldung mit Benutzername und Passwort (“Basic Auth”) ist möglich.
Das System unterstützt auch sogenannte JWTs (JSON Web Tokens).

🔗 Was sind verknüpfte Inhalte?

Manchmal sind Daten miteinander verknüpft, z.B. ein Artikel mit einem Bild. Standardmäßig bekommst du nur die ID des Bildes:


{
  "@id": "...",
  "image": [{ "@id": "..." }]
}

Mit dem Zusatz include=image bekommst du die Bilddaten direkt dazu:


{
  "image": [{
    "@id": "...",
    "name": "Tim Berners-Lee, 2014",
    "contentUrl": "https://...jpg"
  }]
}

Du kannst das auch verschachteln, z.B. include=image.author – dann bekommst du auch Infos zum Fotografen.

🧠 Wie frage ich nur bestimmte Felder ab?

Oft brauchst du nicht alle Infos, sondern nur bestimmte Felder. Mit fields bestimmst du, was du bekommst:

GET /api/v4/persons?fields=name

GET /api/v4/persons?fields=,dc:classification.

In Kombination mit include kannst du auch gezielt Felder von verknüpften Inhalten abfragen:

GET /api/v4/persons?include=image,image.author&fields=name,image.contentUrl,image.author.name

Tipp: Für importierte Datensätze: fields=identifier zeigt externe IDs an.

🛠 Praktische Beispiele zum Ausprobieren

Alle Personen mit Name und Bild-URL:

curl “https://meinserver/datacycle/api/v4/persons?fields=name,image.contentUrl&include=image&token=DEIN_TOKEN”

Alle Artikel mit Titel und Veröffentlichungsdatum:

curl “https://meinserver/datacycle/api/v4/articles?fields=title,date&token=DEIN_TOKEN”

Fehlermeldung “Unauthorized”? Prüfe, ob dein Token korrekt ist oder du angemeldet bist.