API-Übersicht

Die Hochzeitshelfer API ermöglicht dir den programmatischen Zugriff auf deine Hochzeitsdaten. Über die REST-API kannst du z. B. Gästedaten auslesen, erstellen, aktualisieren oder löschen — ideal für eigene Integrationen, Automatisierungen oder Drittanbieter-Tools.

Voraussetzung

Der API-Zugang ist eine Premium-Funktion. Premium Du benötigst ein entsprechendes Abo, um API-Tokens erstellen und die API nutzen zu können.

Basis-URL

Alle API-Endpunkte sind unter folgender Basis-URL erreichbar:

https://hochzeitshelfer.app/api/v1

Versionierung

Die API verwendet URL-basierte Versionierung. Die aktuelle Version ist v1. Alle Endpunkte beginnen mit /api/v1/.

Authentifizierung

Die API nutzt Bearer-Token-Authentifizierung über Laravel Sanctum. Du erstellst API-Tokens in den Einstellungen der App und sendest sie im Authorization-Header mit.

Authorization: Bearer DEIN_API_TOKEN

Mehr Details findest du unter Authentifizierung.

Anfrage-Format

• Content-Type: application/json
• Accept: application/json
• Alle Request-Bodys werden als JSON gesendet

Beispiel eines vollständigen Requests:

curl -X GET https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Antwort-Format

Alle erfolgreichen Antworten werden als JSON zurückgegeben und folgen einem einheitlichen Format:

Einzelne Ressource:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Max",
    ...
  }
}

Liste von Ressourcen:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Max",
      ...
    },
    ...
  ]
}

Rate Limiting

Die API erlaubt maximal 60 Anfragen pro Minute pro authentifiziertem Benutzer. Wird das Limit überschritten, erhältst du eine 429 Too Many Requests-Antwort.

IDs

Alle Ressourcen verwenden UUIDs als Identifikatoren (z. B. 550e8400-e29b-41d4-a716-446655440000), keine fortlaufenden Nummern.

Hochzeits-Kontext

Alle API-Aufrufe beziehen sich automatisch auf deine aktive Hochzeit. Wenn du mehrere Hochzeiten verwaltest, werden die Daten der aktuell aktiven Hochzeit zurückgegeben.

Verfügbare Endpunkte

Ressource	Beschreibung	Dokumentation
Gäste	Gästedaten verwalten (CRUD)	Gäste-API

Fehlerbehandlung

Die API verwendet standardmäßige HTTP-Statuscodes:

Statuscode	Bedeutung
200	Erfolgreich
204	Erfolgreich (kein Inhalt, z. B. nach Löschen)
401	Nicht authentifiziert — Token fehlt oder ist ungültig
403	Zugriff verweigert — fehlende Berechtigung oder kein Premium-Abo
404	Ressource nicht gefunden
422	Validierungsfehler — ungültige Daten
429	Zu viele Anfragen — Rate Limit überschritten

Validierungsfehler (422)

Bei ungültigen Daten gibt die API eine detaillierte Fehlermeldung zurück:

{
  "message": "The given data was invalid.",
  "errors": {
    "first_name": ["The first name field is required."]
  }
}

Fehlende Berechtigung (403)

Wenn dein Abo keinen API-Zugang beinhaltet:

{
  "message": "Api Access ist nur mit einem Premium-Plan verfügbar.",
  "feature": "api_access"
}