API-Grundlagen

Die öffentliche API ist eine JSON-API über HTTP. Sie ist versioniert und liegt unter /api/v1. Alle Endpunkte der öffentlichen API erfordern Eventwerk Plus.

Basisadresse

Die Basisadresse lautet https://api.eventwerk.eu/api/v1. Ein Aufruf von /me wird damit zu GET https://api.eventwerk.eu/api/v1/me.

Anmeldung

Jede Anfrage trägt einen API-Schlüssel im Header Authorization. Das Format ist Bearer ew_.... Ein Schlüssel beginnt mit ew_, gefolgt von 40 Zeichen. Er handelt immer als Eigentümer der Organisation.

curl -s https://api.eventwerk.eu/api/v1/me \
  -H "Authorization: Bearer ew_..."

Schlüssel anlegen und zurückziehen

1. Plan in den Einstellungen auf Eventwerk Plus stellen.
2. Als Eigentümer unter Einstellungen, API-Schlüssel einen Namen angeben und den Schlüssel anlegen.
3. Den vollen Schlüssel jetzt kopieren. Er wird nur einmal angezeigt.
4. Nicht benötigte Schlüssel in den Einstellungen zurückziehen.

• Höchstens 25 aktive Schlüssel pro Organisation.
• Höchstens 10 neue Schlüssel in einem rollierenden Zeitfenster von 24 Stunden.
• Ein zurückgezogener Schlüssel wird sofort abgelehnt und ergibt invalid_api_key.
• Der angezeigte Prefix besteht aus den ersten acht Zeichen.
• Zu jedem Schlüssel werden der Name und der Zeitpunkt der letzten Nutzung geführt. Die Einstellungen zeigen beides an. Der Zeitpunkt steht als last_used_at in der Antwort der Schlüssel-Endpunkte. Vor der ersten Nutzung ist er null.

Antwortformat

• JSON mit UTF-8 und Content-Type: application/json; charset=utf-8.
• Zeitpunkte kommen als RFC-3339-Strings in UTC, immer mit dem Suffix Z.
• Die Zeitzone des Events steht getrennt im Feld timezone. Sie ist ein IANA-Name, Standard Europe/Vienna.
• Clients müssen Zeitpunkte selbst in die gewünschte Zeitzone umrechnen. Die API liefert keine lokale Zeit.
• Geldbeträge als ganze Zahl in Cent.
• Unbekannte Felder im Rumpf werden abgelehnt. Die Anfrage ergibt unknown_field, details.field nennt den Feldnamen.
• Der Rumpf darf höchstens 1 MiB groß sein. Sonst ergibt sich request_too_large.

Paginierung

Die Listen unter /events und /events/{eventID}/registrations liefern seitenweise Ergebnisse. Die Antwort hat immer dieselbe Form.

{
  "items": [],
  "has_more": false,
  "next_cursor": null
}

• limit legt die Seitengröße fest. Erlaubt sind 1 bis 200, Standard 50. Ein anderer Wert ergibt invalid_limit.
• cursor setzt die Liste an der Stelle fort, die next_cursor nennt. Ohne Cursor beginnt die Liste vorn.
• updated_since liefert nur Datensätze, die nach dem angegebenen RFC-3339-Zeitpunkt geändert wurden.
• has_more sagt, ob weitere Datensätze folgen. Ist er false, ist next_cursor null.
• Der Cursor ist undurchsichtig. Übernehmen Sie ihn unverändert und verwenden Sie ihn nur für dieselbe Liste.

Idempotenz

POST /events akzeptiert den optionalen Header Idempotency-Key. Damit lässt sich eine Anfrage wiederholen, etwa nach einer Zeitüberschreitung, ohne ein zweites Event anzulegen.

• Gleicher Schlüssel und gleicher Rumpf: Die API liefert dieselbe Antwort erneut.
• Gleicher Schlüssel und anderer Rumpf: Die API antwortet mit Status 409 und dem Code idempotency_conflict.
• Ohne Header legt jeder Aufruf ein neues Event an.
• Verwenden Sie je beabsichtigter Anlage einen eigenen, zufälligen Schlüssel.

Grenzen

Es gelten 200 Anfragen pro Minute je API-Schlüssel. Der Zähler liegt im Arbeitsspeicher jeder Instanz und wird nicht über Instanzen geteilt.

• Hinter mehreren Instanzen liegt das wirksame Limit deshalb faktisch bei einem Vielfachen von 200 pro Minute.
• Nach einem Neustart oder Deploy beginnt die Zählung neu.
• Ist das Limit erreicht, antwortet die API mit Status 429, dem Code rate_limited und dem Header Retry-After in Sekunden.

Grenzen der Gastrouten

Öffentliche Routen ohne API-Schlüssel haben eigene Grenzen je IP-Adresse.

• Anmelde-Link (Magic-Link) anfordern: 20 Anfragen pro Stunde je IP-Adresse.
• Anmeldung zu einem Event: 60 Anfragen pro Stunde je IP-Adresse.
• Zusätzlich höchstens 3 Anmeldungen pro Stunde je E-Mail-Adresse und Event.

Fehler

Fehler haben immer die Form { "code": "...", "message": "..." }. Das Feld details kann zusätzliche Angaben enthalten, etwa field bei unknown_field, count bei event_has_registrations oder limit, used und plan beim Versandkontingent. code ist stabil, message ist für Menschen gedacht.

Nicht verfügbar

• Schreiben von Ticketarten, Nachrichten, Umfragen, Programm oder Team über einen API-Schlüssel.
• CSV-Import, Empfehlungscodes und Erinnerungen über einen API-Schlüssel.
• Zapier-Workflows und Zoom-Anbindung.