# Übersicht

## Worum es geht

Über die externe API verbinden Sie ein anderes System mit einer GATEWatch-Veranstaltung. Sie können verfügbare Eingabefelder ermitteln, Gästedaten auslesen sowie Gäste anlegen und aktualisieren. Diese Anleitung richtet sich an die technische Betreuung der Anbindung.

## Grundlage: Swagger-Beschreibung

Diese Anleitung erläutert die veröffentlichte [Swagger-Dokumentation „External API for GATEWatch“, Version 1.0.0](https://gwatch.events/ext-api). Die zugrunde liegende [OpenAPI-Beschreibung](https://gwatch.events/openapi.json) enthält Endpunkte, Parameter, Antwortmodelle und Beispiele. Die folgenden Seiten ergänzen diese technische Referenz um den praktischen Ablauf und Fehlerbehandlung.

## Die vier Endpunkte

Die Basisadresse für die hier gezeigten Aufrufe lautet `https://gwatch.events/ext-api`.

<table id="bkmrk-methode-endpunkt-auf"><thead><tr><th>Methode</th><th>Endpunkt</th><th>Aufgabe</th><th>Anleitung</th></tr></thead><tbody><tr><td>`GET`</td><td>`/metadata`</td><td>Importierbare Felder, Sprachen und freigegebene Gates ermitteln.</td><td>[Metadaten](https://doc.gwatch.events/books/externes-api/page/abruf-der-metadaten-metadata)</td></tr><tr><td>`GET`</td><td>`/pull`</td><td>Gästeliste in Seiten abrufen; optional nach Änderungen filtern.</td><td>[Listenabruf](https://doc.gwatch.events/books/externes-api/page/abruf-von-gast-daten-als-liste-pull)</td></tr><tr><td>`GET`</td><td>`/fetch`</td><td>Einen Gast über seinen Ticketcode abrufen.</td><td>[Einzelabruf](https://doc.gwatch.events/books/externes-api/page/abruf-von-daten-eines-einzelnen-gastes-fetch)</td></tr><tr><td>`POST`</td><td>`/push`</td><td>Gäste anlegen oder anhand ihres Ticketcodes aktualisieren.</td><td>[Gäste schreiben](https://doc.gwatch.events/books/externes-api/page/hinzufugen-und-aktualisieren-von-gast-daten-push)</td></tr></tbody></table>

Die GET-Aufrufe verwenden URL-Parameter und benötigen keinen JSON-Body. Bei `push` senden Sie den Body als JSON mit `Content-Type: application/json`. Antworten sind grundsätzlich JSON; insbesondere HTTP 401 kann jedoch einen leeren Body haben. Werten Sie deshalb zuerst den HTTP-Status aus.

## Voraussetzungen und Zugang

Fordern Sie beim zuständigen Teilnehmermanagement folgende Angaben an:

- Den **API-Hauptschlüssel** für die richtige, nicht archivierte Veranstaltung.
- Für `pull` und `fetch` eine aktive **Datenansicht (Flavor)** des passenden Typs und deren Schlüssel.
- Für `push` den zusätzlichen **Import-Schlüssel**, den Swagger als erforderlich ausweist.
- Die Freigabe der ausgehenden IP-Adresse Ihres Servers, falls ein IP-Filter besteht.
- Die vereinbarten Ausgabefelder sowie die für den Import freigegebenen Felder und Gates.

### Header und ihre Bedeutung

<table id="bkmrk-header-verwendung-x-" style="width: 100%;"><thead><tr><th style="width: 14.6526%;">Header</th><th style="width: 85.3276%;">Verwendung</th></tr></thead><tbody><tr><td style="width: 14.6526%;">`x-api-key`</td><td style="width: 85.3276%;">Bei allen vier Endpunkten erforderlich. Der Schlüssel bestimmt die Veranstaltung; eine zusätzliche Veranstaltungs-ID wird nicht übergeben.</td></tr><tr><td style="width: 14.6526%;">`x-api-flavor`</td><td style="width: 85.3276%;">Bei `pull` und `fetch`: Schlüssel der jeweiligen Datenansicht. Weglassen funktioniert nur, wenn eine aktive Ansicht mit leerem Schlüssel und passendem Typ eingerichtet ist.</td></tr><tr><td style="width: 14.6526%;">`x-api-push`</td><td style="width: 85.3276%;">Bei `push`: Laut Swagger erforderlicher Import-Schlüssel (`ApiPushHeader`). Den passenden Wert beim Teilnehmermanagement anfordern.</td></tr><tr><td style="width: 14.6526%;">`Accept`</td><td style="width: 85.3276%;">Verwenden Sie `application/json`.</td></tr><tr><td style="width: 14.6526%;">`Content-Type`</td><td style="width: 85.3276%;">Bei `push`: `application/json`.</td></tr></tbody></table>

Ein Flavor für `pull` ist nicht automatisch für `fetch` verwendbar. Die Datenansichten werden getrennt nach Endpunkttyp konfiguriert. `metadata` benötigt keinen Flavor.

Verwenden Sie Schlüssel in den Headern und bewahren Sie sie in der serverseitigen Konfiguration auf. Die Beispiele enthalten nur Platzhalter; sie sind vor einem eigenen Test zu ersetzen.

### IP-Filter

Für die Veranstaltung kann eine Liste erlaubter IP-Adressen hinterlegt sein. Ein eigener, nicht leerer IP-Filter der gewählten Datenansicht **ersetzt** bei `pull` beziehungsweise `fetch` den allgemeinen Filter. Ohne eigenen Filter gilt der allgemeine Filter.

Geprüft wird die vom Portal ermittelte IP-Adresse der Anfrage. Lassen Sie deshalb auch die tatsächliche ausgehende Adresse Ihrer Testumgebung freigeben. Die aktuelle Implementierung vergleicht einzelne Adressen; CIDR-Netze und Wildcards sind keine unterstützte Schreibweise dieser Filter.

## Empfohlener Einstieg

1. Rufen Sie `metadata` ab und kontrollieren Sie den Veranstaltungsnamen.
2. Stimmen Sie die gewünschte Leseansicht mit dem Teilnehmermanagement ab.
3. Prüfen Sie `pull` mit einem kleinen `limit` oder `fetch` mit einem bekannten Test-Ticketcode.
4. Ordnen Sie die Felder Ihres Systems den tatsächlich gelieferten Feldschlüsseln zu.
5. Testen Sie `push` mit abgestimmten Testdaten und kontrollieren Sie jedes Einzelergebnis.

In [Swagger](https://gwatch.events/ext-api) öffnen Sie den gewünschten Endpunkt. Unter **Authorize** hinterlegen Sie die Schlüssel; über **Try it out** geben Sie Parameter beziehungsweise den Request-Body ein und starten mit **Execute** den Aufruf. Die Bereiche **Example Value** und **Schema** zeigen Beispielwerte und die Datenstruktur. **Ein `push`-Aufruf schreibt echte Daten in die über den Hauptschlüssel ausgewählte Veranstaltung.** Verwenden Sie dafür eine vereinbarte Testveranstaltung.

## Schreibfelder und Lesefelder unterscheiden

`metadata.guest` beschreibt die zulässigen **Eingabeschlüssel für `push`**, beispielsweise `GUEST_FIRST_NAME`. **Bei beiden Exportvarianten (`pull` und `fetch`) legt immer die Administration die fachlichen Ausgabefeldnamen und deren Inhalte fest.** Ein Feld kann einen einzelnen Wert oder zusammengesetzte Inhalte enthalten. Beispielsweise kann die Administration ein Feld `Name` definieren, das Vor- und Nachname zusammen ausgibt. Die festen Verwaltungsfelder von `pull` (`id`, `created`, `updated`, `deleted`) werden zusätzlich vom Portal ergänzt.

Kopieren Sie eine Leseantwort daher nicht unverändert in einen Schreibaufruf. Auch Datums-, Listen- und Ja/Nein-Ausgaben sind nicht automatisch geeignete Eingabewerte.

## HTTP-Status im Überblick

<table id="bkmrk-status-bedeutung-200"><thead><tr><th>Status</th><th>Bedeutung</th></tr></thead><tbody><tr><td>`200`</td><td>Erfolgreicher Abruf oder vollständig erfolgreicher `push`.</td></tr><tr><td>`207`</td><td>Bei `push` ist mindestens ein Datensatz fehlgeschlagen; auch alle Datensätze können betroffen sein. `summary` und `results` auswerten.</td></tr><tr><td>`401`</td><td>Zugang abgewiesen: Hauptschlüssel, Archivstatus, Flavor-Typ/Aktivierung, Import-Schlüssel oder IP-Filter prüfen. Der Body kann leer sein.</td></tr><tr><td>`403`</td><td>Bei `fetch`: Ein bestehender Gast erfüllt die Filterbedingungen der Datenansicht nicht.</td></tr><tr><td>`404`</td><td>Bei `fetch`: Kein entsprechender Gast gefunden.</td></tr><tr><td>`422`</td><td>Anfrageparameter beziehungsweise die äußere Struktur des Schreibaufrufs sind ungültig.</td></tr></tbody></table>

Die Antwortstrukturen unterscheiden sich je Endpunkt. Ein Feld `error` ist nicht in jeder Antwort enthalten. Bei unerwarteten Serverfehlern keine automatische Schreibwiederholung ohne Prüfung des bereits gespeicherten Ergebnisses durchführen.

**Weiter:** [Abruf der Metadaten](https://doc.gwatch.events/books/externes-api/page/abruf-der-metadaten-metadata).