Veranstaltungen-APP/docs/API_DOCUMENTATION.md

API Dokumentation

Überblick

Die Veranstaltungen-API bietet Zugriff auf Events, Locations und deren Vorkommen (Termine). Alle Endpoints sind REST-konform und geben JSON zurück.

Base URL: http://localhost:8000/api

---

Events API

1. Alle Events auflisten

GET /events

Beschreibung: Listet alle veröffentlichten Events mit optionalen Filtern auf.

Query Parameter:

• from (optional): Startdatum im Format YYYY-MM-DD
• to (optional): Enddatum im Format YYYY-MM-DD
• category (optional): Filter nach Kategorie
• location (optional): Filter nach Ort oder Stadt
• limit (optional): Anzahl pro Seite (1-100, Standard: 20)

Beispiel:

curl "http://localhost:8000/api/events?category=Kultur&location=Dresden&limit=10"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Jazz-Konzert im Park",
      "description": "...",
      "category": "Musik",
      "location_id": 1,
      "status": "published",
      "location": {
        "id": 1,
        "name": "Tiergarten Berlin",
        "address": {
          "street": "Straße des 17. Juni",
          "house_number": "100",
          "postal_code": "10785",
          "city": "Berlin",
          "state": "Berlin",
          "country": "Germany"
        },
        "contact": {
          "phone": "+49 30 39403501",
          "email": "info@tiergarten.de",
          "website": "https://www.tiergarten.de"
        }
      },
      "occurrences": [
        {
          "id": 1,
          "start_datetime": "2026-04-18T10:00:00Z",
          "end_datetime": "2026-04-18T18:00:00Z",
          "status": "scheduled"
        }
      ]
    }
  ],
  "pagination": {
    "total": 42,
    "per_page": 20,
    "current_page": 1,
    "last_page": 3
  }
}

---

2. Einzelnes Event anzeigen

GET /events/{id}

Beschreibung: Zeigt ein einzelnes veröffentlichtes Event mit allen seinen Terminen.

Path Parameter:

• id (erforderlich): Event ID

Beispiel:

curl "http://localhost:8000/api/events/1"

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Jazz-Konzert im Park",
    "description": "...",
    "category": "Musik",
    "location": { ... },
    "occurrences": [ ... ]
  }
}

Response (404 Not Found): Event nicht veröffentlicht oder existiert nicht.

---

Locations API

3. Verfügbare Veranstaltungsorte

GET /events/locations/list

Beschreibung: Listet alle verfügbaren Veranstaltungsorte mit vollständigen Adressinformationen auf.

Beispiel:

curl "http://localhost:8000/api/events/locations/list"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Tiergarten Berlin",
      "address": {
        "street": "Straße des 17. Juni",
        "house_number": "100",
        "postal_code": "10785",
        "city": "Berlin",
        "state": "Berlin",
        "country": "Germany",
        "full_address": "Straße des 17. Juni 100, 10785 Berlin, Germany",
        "short_address": "10785 Berlin"
      },
      "contact": {
        "phone": "+49 30 39403501",
        "email": "info@tiergarten.de",
        "website": "https://www.tiergarten.de"
      },
      "event_count": 1
    }
  ]
}

---

Utilities API

4. Verfügbare Kategorien

GET /events/categories/list

Beschreibung: Listet alle verfügbaren Event-Kategorien auf.

Beispiel:

curl "http://localhost:8000/api/events/categories/list"

Response (200 OK):

{
  "success": true,
  "data": [
    "Musik",
    "Theater",
    "Sport",
    "Film",
    "Kulinarik",
    "Kunst",
    "Literatur",
    "Wellness",
    "Festival",
    "Technologie"
  ]
}

---

Fehlerbehandlung

Fehler-Response Format

{
  "success": false,
  "message": "Beschreibung des Fehlers",
  "errors": {
    "field": ["Validierungsfehler"]
  }
}

HTTP Status Codes

• 200 OK: Erfolgreich
• 404 Not Found: Ressource nicht gefunden
• 422 Unprocessable Entity: Validierungsfehler
• 500 Internal Server Error: Serverfehler

---

Filterbeispiele

Events nach Kategorie filtern

curl "http://localhost:8000/api/events?category=Musik"

Events nach Ort filtern

curl "http://localhost:8000/api/events?location=Berlin"

Events in Zeitraum filtern

curl "http://localhost:8000/api/events?from=2026-04-15&to=2026-05-31"

Kombinierte Filter

curl "http://localhost:8000/api/events?category=Kultur&location=Dresden&from=2026-04-15&limit=5"

---

Swagger UI

Eine interaktive API-Dokumentation ist verfügbar unter: http://localhost:8000/api/docs

Hier kannst du:

• Alle Endpoints visualisieren
• Parameter testen
• Response-Strukturen sehen
• API-Calls direkt ausführen

---

Rate Limiting

Aktuell gibt es keine Rate-Limits. Dies kann in Zukunft implementiert werden.

---

Versionierung

Aktuelle API-Version: 1.0.0

Zukünftige Breaking Changes werden durch eine neue Major-Version gekennzeichnet (z.B. /api/v2/...).

---

Support

Bei Fragen oder Problemen: support@veranstaltungen.de