# 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:

```json
"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:

- `key`: Hier findet sich der Schlüssel des Feldes, welcher zum Hinzufügen und Bearbeiten genutzt werden muss.
- `name`: Dieser Name dient zur Kommunkation mit dem Teilnehmermanagement, damit alle wissen um welches Feld es sich handelt.
- `type`: Der Typ des Feldes, welche bestimmte Validierungsregeln impliziert.   
    
    - `multiLineText`: Text, der Zeilenumbrüche enthalten darf.
    - `singleLineText`: Text, der keine Zeilenumbrüche enthalten darf.
    - `email`: Der Inhalt muss eine formal gültige E-Mail-Adresse sein.
    - `url`: Der Inhalt muss eine formal gültige URL sein.
    - `numeric`: Der Inhalt muss eine formal gültige Zahl im "Decimal Point Notation"-Format sein.
    - `integer`: Der Inhalt muss eine formal gültige Ganzzahl sein.
    - `boolean`: Der Inhalt kann "Yes", "No", 1, 0, true oder false sein.
    - `date`: Format muss `YYYY-MM-DD` sein, z. B. `2025-04-08`.
    - `dateTime`: Format muss `YYYY-MM-DDTHH:MM:SS` sein, z. B. `2025-04-08T14:38:14`. Zeitzonenangaben werden nicht verwendet.
    - `list`: Die möglichen Optionen werden als Key-Value-Paare angegeben. Beim Hinzufügen oder Bearbeiten von Gästen ist der **Key** zu verwenden, bei der Abfrage wird die **lokalisierte Value** zurückgegeben (abhängig von der gewählten Sprache).

Beispiel:

```json
"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:

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