Externes API

GATEWatch verfügt über ein externes API zum Auslesen und Hinzufügen, sowie Ändern von Gästen.

Übersicht

Zugang zur API

Für die Nutzung der API ist mindestens ein gültiger API-Schlüssel erforderlich (Hauptschlüssel). Dieser kann über das zuständige Teilnehmermanagement bezogen werden. Abhängig vom Anwendungsfall können zusätzlich weitere Schlüssel zur Verfügung gestellt werden. Die Verwendung und Funktion der einzelnen Schlüssel wird im weiteren Verlauf dieser Dokumentation erläutert. Kann die Authentifizierung nicht erfolgreich durchgeführt werden kommt es zu einem HTTP 401 Fehler.

Zusätzlich kann der Zugriff auf die API über eine IP-Filterung eingeschränkt werden. Es wird empfohlen, die IP-Adresse(n) der anfragenden Server (inkl. Testumgebungen) im Vorfeld zu definieren und bereitzuhalten. Schlägt die Prüfung der IP Adresse fehl, kommt es zu einem HTTP 401 Fehler.

Die API verwendet JSON (JavaScript Object Notation) als Austauschformat. Anfragen an die API sowie die von ihr zurückgegebenen Antworten müssen im JSON-Format strukturiert bzw. verarbeitet werden.

API-Endpunkte

Die API bietet drei dedizierte Endpunkte zur Interaktion:

Weitere Informationen

Die genaue Struktur der Anfragen, das erwartete JSON-Format sowie mögliche Fehlermeldungen und Antwort-Codes werden auf den folgenden Seiten ausführlich beschrieben.

Falls Sie die API online testen möchten, besuchen Sie:
https://gwatch.events/ext-api

Abruf der Metadaten (metadata)

Aufruf

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

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

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

Struktur der Antwort

Die Antwort der API ist in drei logische Bereiche gegliedert:

1. Veranstaltungsinformationen

Dieser Abschnitt enthält allgemeine Informationen zur Veranstaltung. Besonders wichtig ist hier der Eintrag zur Standardlänge des Ticketcodes. Dieser Wert ist beim Hinzufügen neuer Gäste relevant, um sicherzustellen, dass keine Konflikte mit bestehenden Codes entstehen. Es kann ein längerer oder kürzerer Code verwendet werden, sofern er eindeutig ist.

Zusätzlich werden die in der Veranstaltung verfügbaren Sprachen mitgeliefert. Diese Informationen dienen dazu, beim Erstellen oder Aktualisieren von Gästen die passende Sprache zu wählen.

Beispiel:

"event": {
        "name": "IT-Seminar",
        "date": "2025-05-31",
        "defaultTicketCodeLength": 10,
        "locales": [
            "de", "en"
        ]
    },

2. Verfügbare Felder für Gäste

In diesem Abschnitt werden alle Felder aufgeführt, die beim Hinzufügen oder Bearbeiten von Gästen verwendet werden können. Enthält ein Feld spezifische Restriktionen, so sind diese im jeweiligen Feld mit angegeben. Wenn in den Restriktionen "nullable": false angegeben ist, bedeutet dies, dass das Feld beim Einfügen oder Bearbeiten nicht mit einem Nullwert übergeben werden darf. Sind für das Feld keine Daten vorhanden, kann es aber einfach weggelassen werden. 

Jedes Feld enthält mindestens folgende Informationen:

Beispiel:

"guest": {
      "key": "GUEST_TICKET_CODE",
      "name": "Ticket code",
      "type": "singleLineText",
      "restrictions": {
          "nullable": false
          "unique": true,
          "min": 4,
          "max": 128
      }
  },
  {
      "key": "GUEST_LOCALE",
      "name": "Locale",
      "type": "list",
      "items": [
          {
              "key": "de",
              "value": "Deutsch"
          }
      ],
      "restrictions": {
          "nullable": false
      }
  },
  {
      "key": "GUEST_DINNER",
      "name": "Teilnahme am Abendessen",
      "type": "boolean"
  },
  . . . .
}

3. Gates (Zugangsbereiche)

Der dritte Bereich enthält Informationen zu sogenannten Gates. Diese abstrakten Einheiten können verschiedene Bedeutung haben – zum Beispiel Veranstaltungstage, Sessions, Vorträge oder anderweitig geschützte Bereiche.

Diese Informationen dienen dazu, Gästen beim Erstellen oder Bearbeiten bestimmte Gates zuzuordnen. Eine detaillierte Verwendung wird im Abschnitt zum pull-Aufruf erläutert.

Beispiel:

"gates: [
    {
        "id": 6398,
        "name": "Sicherheit von Websites"
    },
    {
        "id": 6399,
        "name": "Anti-Viren Software aktuell"
    },
    . . . .
  ]
}

Abruf von Gast-Daten als Liste (pull)

Aufruf

Der Abruf der Gast-Daten als Liste 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:

Zusatzinformationen je Datensatz

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

Lokalisierte Darstellung

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

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:

Beispiel (Erfolgreiche Antwort):

{
    "error": false,
    "meta": {
        "changesUntil": "2025-02-23T15:00:00",
        "available": 19,
        "limit": 1,
        "offset": 0,
        "nextUrl": "https://gwatch.events/ext-api/pull?limit=1&offset=1&changesUntil=2025-02-23T15:00:00"
    },
    "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
        }
        . . . . 
    ]
}

Abruf von Daten eines einzelnen Gastes (fetch)

Aufruf

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

https://gwatch.events/ext-api/fetch?code=<Ticketcode>

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.

Notwendiger GET-Parameter

Folgender Parameter muss zusätzlich in der URL übergeben werden:

Lokalisierte Darstellung

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

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

Statusmeldungen und Rückgabeformat

Beispiel (Erfolgreiche Antwort):

{
    "Vorname": "Susi",
    "Nachname": "Sorglos",
    "Mitgliedschaft": "IT-Security Concepts"
}

Hinzufügen und Aktualisieren von Gast-Daten (push)

Aufruf

Die Übertragung erfolgt über eine HTTP-POST-Anfrage an folgende URL:

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

Authentifizierung

Folgende Header müssen gesetzt werden:

Request-Body (Payload)

1. meta

Enthält Steuerparameter für das Importverhalten:

2. guests

Enthält ein Array mit bis zu 100 Gast-Datensätzen. Jeder Datensatz ist ein Key-Value-Objekt, basierend auf den Feldern aus /metadata.

Besonderheiten:

Beispiel-Request

{
  "meta": {
    "failIfExists": false,
    "insertAs": 2
  },
  "guests": [
    {
      "GUEST_FIRST_NAME": "Max",
      "GUEST_LAST_NAME": "Mustermann",
      "GUEST_EMAIL": "max@example.com",
      "GUEST_TICKET_CODE": "ABC123",
      "gates": [1, 3]
    }
  ]
}

Response

HTTP Status Codes:

Beispiel für HTTP 422

Request

{
    "meta": {
        "failIfExists": true,
        "insertAs": 3
    },
    "guests": [
        {
            "GUEST_TICKET_CODE": "223345",
            "GUEST_FIRST_NAME": "Hans",
            "GUEST_LAST_NAME": "Hermann",
            "gates": [6398]
        },
        {
            "GUEST_TICKET_CODE": "4711",
            "GUEST_FIRST_NAME": "Susi",
            "GUEST_LAST_NAME": "Sorglos",
            "gates": [6399]
        }
    ]
}

Response

{
    "error": true,
    "message": {
        "meta.insertAs": [
            "The value may not be greater than 2."
        ]
    }
}

Erfolgreiche oder Teilerfolgreiche Verarbeitung (HTTP 200, HTTP 207):

Der Response gliedert sich in zwei Bereiche:

1. summary

2. results

Gibt für jeden Datensatz an, ob die Verarbeitung erfolgreich war oder nicht.

Beispiel für HTTP 207

Request:

{
    "meta": {
        "failIfExists": false,
        "insertAs": 2
    },
    "guests": [
        {
            "GUEST_TICKET_CODE": "223344",
            "GUEST_FIRST_NAME": "Hans",
            "GUEST_LAST_NAME": "Hermann",
            "GUEST_EMAIL": "didi@aol.com",
            "gates": [6398]
        },
        {
            "GUEST_FIRST_NAME": "Frank",
            "GUEST_LAST_NAME": "Fuhrmann",
            "GUEST_EMAIL": "ffuhrmann@aol",
            "gates": [6398]
        },
        {
            "GUEST_TICKET_CODE": "4711",
            "GUEST_FIRST_NAME": "Susi",
            "GUEST_LAST_NAME": "Sorglos",
            "gates": [6399,4]
        },
        {
            "TICKET_CODE": "4712",
            "GUEST_FIRST_NAME": "Didi",
            "GUEST_LAST_NAME": "Dröge",
            "gates": [6399]
        }
    ]
}

Response:

{
    "summary": {
        "total": 4,
        "created": 0,
        "updated": 1,
        "failed": 3
    },
    "results": [
        {
            "index": 0,
            "ticketCode": "223344",
            "id": 3247987,
            "status": "updated",
            "message": null
        },
        {
            "index": 1,
            "ticketCode": null,
            "id": null,
            "status": "failed",
            "message": {
                "GUEST_EMAIL": [
                    "Please enter a valid email address."
                ]
            }
        },
        {
            "index": 2,
            "ticketCode": "4711",
            "id": 3247986,
            "status": "failed",
            "message": {
                "gates.1": [
                    "The selected gates.1 is invalid."
                ]
            }
        },
        {
            "index": 3,
            "ticketCode": null,
            "id": null,
            "status": "failed",
            "message": "The following keys are not available: TICKET_CODE"
        }
    ]
}