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:**
```bash
curl "http://localhost:8000/api/events?category=Kultur&location=Dresden&limit=10"
```

**Response (200 OK):**
```json
{
  "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:**
```bash
curl "http://localhost:8000/api/events/1"
```

**Response (200 OK):**
```json
{
  "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:**
```bash
curl "http://localhost:8000/api/events/locations/list"
```

**Response (200 OK):**
```json
{
  "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:**
```bash
curl "http://localhost:8000/api/events/categories/list"
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    "Musik",
    "Theater",
    "Sport",
    "Film",
    "Kulinarik",
    "Kunst",
    "Literatur",
    "Wellness",
    "Festival",
    "Technologie"
  ]
}
```

---

## Fehlerbehandlung

### Fehler-Response Format
```json
{
  "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
```bash
curl "http://localhost:8000/api/events?category=Musik"
```

### Events nach Ort filtern
```bash
curl "http://localhost:8000/api/events?location=Berlin"
```

### Events in Zeitraum filtern
```bash
curl "http://localhost:8000/api/events?from=2026-04-15&to=2026-05-31"
```

### Kombinierte Filter
```bash
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**