Direkt zum Hauptinhalt

Abruf von Gast-Daten (pull)

Aufruf

Der Abruf der Gast-Daten erfolgt über eine HTTP-GET-Anfrage an folgende URL:

https://gwatch.events/ext-api/pull

Zur Authentifizierung ist im Request-Header der API-Hauptschlüssel mit dem Schlüssel X-Api-key zu übergeben. Kann die Authentifizierung nicht erfolgreich durchgeführt werden kommt es zu einem HTTP 401 Fehler.

Varianten / Datenansichten

Die zurückgegebenen Inhalte können serverseitig individuell konfiguriert werden. Falls mehrere Varianten (sogenannte Flavors) existieren, erhalten Sie für jede Variante einen separaten Schlüssel, der im Header als X-Api-flavor übergeben werden muss. Kann die Authentifizierung nicht erfolgreich durchgeführt werden kommt es zu einem HTTP 401 Fehler.

Für jede Variante kann optional ein eigener IP-Filter definiert sein. Schlägt die Prüfung der IP Adresse fehl, kommt es zu einem HTTP 401 Fehler.

Optionale GET-Parameter

Folgende Parameter können zusätzlich in der URL übergeben werden:

  • limit
    Die API liefert pro Aufruf maximal 2.500 Datensätze zurück.
    Bei komplexen internen Berechnungen (z. B. bei kombinierten Feldwerten) kann eine Reduktion des Limits hilfreich sein, um Timeouts zu vermeiden.
  • offset
    Um mehr als limit Datensätze abzufragen, kann ein Offset-Wert verwendet werden. Fehlt dieser, wird automatisch 0 angenommen.
    Beispielhafte Paginierung:
    • 1. Aufruf: limit=100
    • 2. Aufruf: limit=100&offset=100
    • 3. Aufruf: limit=100&offset=200
    • usw.
  • changesUntil
    Zur effizienten Synchronisation Ihres Datenbestands können Sie mit diesem Parameter nur Datensätze abrufen, die seit einem bestimmten Zeitpunkt geändert wurden.
    Format: YYYY-MM-DDTHH:MM:SS
    Beispiel: changesUntil=2025-04-08T15:00:00

Zusatzinformationen je Datensatz

Unabhängig von den für Sie konfigurierten Feldern enthält jeder zurückgegebene Datensatz folgende Zusatzinformationen:

  • ID: Die eindeutige Datenbank-ID des Gastes.
  • created: Zeitstempel der Erstellung des Datensatzes.
  • updated: Zeitstempel der letzten Änderung.
  • deleted: true oder false.
    Wurde ein Gast zwischenzeitlich gelöscht, wird dies über dieses Feld signalisiert. So können Sie auch in Ihrem System entsprechende Einträge entfernen. In diesem Fall sind alle konfigurierten Felder im Datensatz leer.

Lokalisierte Darstellung

Die Ausgabe der Daten erfolgt für jeden Gast lokalisiert, das heißt:

  • Datumsangaben, Zeitstempel und Zahlen mit Dezimalstellen werden entsprechend der Sprache des Gastes formatiert.
  • Listenfelder enthalten als Wert die lokalisierte Bezeichnung im Kontext der Sprache des Gastes (nicht den Schlüssel).

Dies gewährleistet eine benutzerfreundliche Darstellung der Daten im jeweiligen Sprachkontext.

Fehlermeldungen und Rückgabeformat

Im Fehlerfall gibt die API eine strukturierte Rückmeldung und den HTTP Fehler 422 zurück. Das Feld error ist in diesem Fall auf true gesetzt. Das Feld message enthält die genaue Beschreibung des Fehlers.

Beispiel (Fehlerhafte Anfrage):

{
    "error": true,
    "message": {
        "limit": [
            "The limit must be at least 1."
        ]
    }
}

Im Erfolgsfall ist error auf false gesetzt. Die Antwortstruktur gliedert sich in:

  • meta: Enthält Informationen zu den verwendeten Parametern und verfügbaren Datensätzen.
  • event: Liste der konfigurierten Felder zur Veranstaltung.
  • guests: Liste der gefundenen Gast-Datensätze. Bis auf die letzten vier Schlüssel id, created, updated und deleted können alle Schlüssel frei vereinbart werden. Sie folgenentsprechen nicht derzwingend den Schlüsselwerten des /metadata Aufrufs, da die Inhalt hier aus verschiedenen Quellen kombiniert und z.T. auch berechnet werden können.

Beispiel (Erfolgreiche Antwort):

{
    "error": false,
    "meta": {
        "changesUntil": "2025-02-23T15:00:00",
        "available": 19,
        "limit": 1,
        "offset": 0
    },
    "event": [
        "name": "IT-Forum"
    ],
    "guests": [
        {
            "Vorname": "Susi",
            "Nachname": "Sorglos",
            "Mitgliedschaft": "IT-Security Concepts",
            "Letzter Scan": "20.03.2025 19:57:57",
            "id": 347639,
            "created": "2017-01-07T20:08:30",
            "updated": "2025-03-20T20:13:47",
            "deleted": false
        }
        . . . . 
    ]
}
nach oben