ThüCAT API-Schnittstelle

Schnittstelle /api/sync

 

Vorbemerkung


Diese Schnittstelle löst die die Schnittstelle /externa-syc/ ab. Neuen Anwendern der ThüCAT-Daten wird ausschließlich diese Schittstelle angeboten. Bisherige Anwender der ThüCAT-Daten (vor dem 30.06.2026) können bei Bedarf auch neue Konfigurationen für die Schnittstelle /external-sync/ anfordern.

Schnittstellenbeschreibung

 

URLs

Im Rahmen der Schnittstelle stehen vier URLs bereit:

  • /api/sync/<ID>/list-changed
  • /api/sync/<ID>/list-expired
  • /api/sync/<ID>/records
  • /api/sync/<ID>/jsonld

 

Authentifizierung

Zur Authentifizierng ist ein API-Key erforderlich. Übergeben Sie folgende Werte:

Key: Authorization

Value: APIKEY <API-Key> (Beispiel: APIKEY 1234abcd-ab12-cd34-ef56-12345678ijkl)

Add to: Header

 

Liste geänderter Datensätze (/list-changed)

Der Abruf von Informationen zu geänderten, angelegten oder entfernten Datensätzen wird über /api/sync/<ID>/list-changed durchgeführt. Mithilfe der URL-Query-Parameter since und until kann der Zeitraum eingeschränkt werden. Die Eingabe kann als Zeitstempel oder nach ISO 8601 erfolgen.

Das Ergebnis ist eine Liste der Datensatz-IDs gruppiert nach Zustand (createdOrUpdated, removed).

⠇
Achtung
Um eine Auflistung der entfernten Datensätze zu erhalten, muss mindestens der Parameter since gesetzt werden.

 

Abgelaufene Veranstaltungen (/list-expired) (nur für Objekte der Domainspecification ttgds:Event)

Der Abruf der IDs abgelaufener Veranstaltungen wird über /api/sync/<ID>/list-expired durchgeführt. Mit dem Parameter since kann eingeschränkt werden, ab wann das Ablaufdatum liegen soll.

Das Ergebnis ist eine Liste der Datensatz-IDs (expired) mit zugehöriger Gesamtanzahl.

⠇
Info
Falls die konfigurierten Indizes keine Veranstaltungen enthalten, ist die Antwort eine leere Liste.

 

Datensatzinhalte (/records)

Abruf der vollständigen indexierten Datensatzinhalte (basedata, geodata, eventdata, linked, jsonld, etc.).

Die Datensätze werden seitenweise ausgegeben. Für die nächste Seite wird ein pageToken in der Antwort mitgegeben:

{
  "records": [ ... ],
  "pageToken": "eyJwaXRJZCI6Ii4uLiIsInNlYXJjaEFmdGVyIjpbLi4uXX0"
}

Der pageToken ist für 10 Minuten gültig und wird bei jedem weiteren Aufruf erneuert.

⠇
ACHTUNG
Wird dieser Zeitraum überschritten, antwortet die API mit HTTP 410 (Gone). Die Paginierung muss dann ohne pageToken neu gestartet werden.

 

Mit den Parametern expandLinks und expandFormat können verknüpfte Datensätze (linked) inline aufgelöst werden. Anstelle der Stub-Objekte (_id, _type) werden die vollständigen Inhalte im gewählten Format zurückgegeben.

Beispiel: ?expandLinks=schema_image,schema_audience&expandFormat=basedata

 

JSON-LD-Daten (/jsonld)

Abruf nur der JSON-LD-Rohdaten. Ebenfalls seitenweise mit pageToken-Paginierung.

Parameterübersicht

  • since (Zeitstempel/ISO 8601) – Startzeitpunkt für die Abfrage. Notwendig für die Auflistung entfernter Datensätze.

    ⠇
    TIP
    Auf einen Zeitpunkt in der nahen Vergangenheit setzen (z.B. vor 10 Minuten), um Datensätze auszuschließen, die gerade noch bearbeitet werden.

  • until (Zeitstempel/ISO 8601) – Endzeitpunkt für die Abfrage. Optional.

  • pageSize (integer) – Anzahl der Datensätze pro Seite. Maximal: 250, Standard: 100

  • pageToken (string) – Opaker Token für die nächste Seite. Wird in der Antwort mitgegeben, solange weitere Seiten vorhanden sind.

  • dateFormat (iso | timestamp) – Datumsformat in der Antwort. Standard: timestamp

  • expandLinks (string) – Kommagetrennte Eigenschaftsnamen, deren verknüpfte Datensätze aufgelöst werden sollen (z.B. schema_image oder schema:image). Optional. Nur für /records.

  • expandFormat (jsonld | minimal | geodata | basedata | eventdata | specificdata | dates) – Antwortformat für aufgelöste verknüpfte Datensätze. Erforderlich wenn expandLinks gesetzt ist. Nur für /records.