# API Beispiele - Media API v1.0

Diese Dokumentation enthält Beispiel-JSONs für alle API-Endpunkte, um zu zeigen wie Daten ausgelesen werden und was beim Anlegen übergeben werden muss.

Base URL: `/api`

---

## MEDIA ENDPOINTS

### GET /api/media
Alle Medien abrufen mit Filterung und Pagination.

**Query Parameter:**
- `category` - Filter nach Kategorie (Movie, TV, Album, etc.)
- `type` - Filter nach Typ
- `search` - Suche in Titel und Beschreibung
- `page` - Seitennummer (Standard: 1)
- `limit` - Ergebnisse pro Seite (Standard: 20)

**Beispiel Request:**
```
GET /api/media?category=Movie&page=1&limit=10
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Inception",
        "year": 2010,
        "poster": "https://example.com/poster.jpg",
        "banner": null,
        "description": "A thief who steals corporate secrets through dream-sharing technology.",
        "rating": 8.8,
        "category": "Movie",
        "type": "Movie",
        "status": "Released",
        "aspectRatio": "2.39:1",
        "runtime": 148,
        "director": "Christopher Nolan",
        "writer": "Christopher Nolan",
        "releaseDate": "2010-07-16",
        "createdAt": "2024-01-15 10:30:00",
        "updatedAt": "2024-01-15 10:30:00"
      }
    ],
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}
```

---

### GET /api/media/:id
Ein einzelnes Medium abrufen mit allen Relationen (Genres, Tags, Studios, Cast).

**Beispiel Request:**
```
GET /api/media/1
```

**Beispiel Response (Movie):**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Inception",
    "year": 2010,
    "poster": "https://example.com/poster.jpg",
    "banner": null,
    "description": "A thief who steals corporate secrets through dream-sharing technology.",
    "rating": 8.8,
    "category": "Movie",
    "type": "Movie",
    "status": "Released",
    "aspectRatio": "2.39:1",
    "runtime": 148,
    "director": "Christopher Nolan",
    "writer": "Christopher Nolan",
    "releaseDate": "2010-07-16",
    "createdAt": "2024-01-15 10:30:00",
    "updatedAt": "2024-01-15 10:30:00",
    "genres": ["Sci-Fi", "Action", "Thriller"],
    "tags": ["Mind-bending", "Dream", "Heist"],
    "studios": ["Warner Bros.", "Legendary Pictures"],
    "staff": [
      {
        "id": 1,
        "name": "Leonardo DiCaprio",
        "photo": "https://example.com/leo.jpg",
        "bio": "American actor and film producer",
        "birthDate": "1974-11-11",
        "birthPlace": "Los Angeles, California",
        "role": "Actor",
        "characterName": "Dom Cobb",
        "characterImage": null,
        "occupations": ["Actor", "Producer"]
      }
    ]
  }
}
```

**Beispiel Response (TV Series mit Episoden):**
```json
{
  "success": true,
  "data": {
    "id": 2,
    "title": "Breaking Bad",
    "year": 2008,
    "poster": "https://example.com/bb-poster.jpg",
    "description": "A high school chemistry teacher turned methamphetamine manufacturer.",
    "rating": 9.5,
    "category": "TV",
    "type": "TV",
    "status": "Ended",
    "runtime": 49,
    "director": "Vince Gilligan",
    "writer": "Vince Gilligan",
    "releaseDate": "2008-01-20",
    "genres": ["Crime", "Drama", "Thriller"],
    "tags": ["Anti-hero", "Drug Trade", "New Mexico"],
    "studios": ["Sony Pictures Television"],
    "staff": [],
    "episodes": [
      {
        "id": 1,
        "media_id": 2,
        "season": 1,
        "episode_number": 1,
        "title": "Pilot",
        "description": "Walter White is diagnosed with lung cancer.",
        "air_date": "2008-01-20",
        "duration": 49,
        "thumbnail": "https://example.com/ep1.jpg"
      }
    ],
    "seasons": [
      {
        "season": 1,
        "episode_count": 7,
        "first_air_date": "2008-01-20",
        "last_air_date": "2008-03-09"
      }
    ]
  }
}
```

**Beispiel Response (Album mit Tracks):**
```json
{
  "success": true,
  "data": {
    "id": 3,
    "title": "Dark Side of the Moon",
    "year": 1973,
    "poster": "https://example.com/album-cover.jpg",
    "description": "Eighth studio album by Pink Floyd",
    "rating": 9.2,
    "category": "Music",
    "type": "Album",
    "status": "Released",
    "genres": ["Progressive Rock", "Psychedelic Rock"],
    "tags": ["Classic", "Concept Album"],
    "studios": ["Harvest Records"],
    "staff": [],
    "tracks": [
      {
        "id": 1,
        "media_id": 3,
        "track_number": 1,
        "title": "Speak to Me",
        "duration": "1:30",
        "artist": "Pink Floyd"
      },
      {
        "id": 2,
        "media_id": 3,
        "track_number": 2,
        "title": "Breathe",
        "duration": "2:43",
        "artist": "Pink Floyd"
      }
    ]
  }
}
```

---

### POST /api/media
Neues Medium erstellen.

**Request Body (Movie):**
```json
{
  "title": "The Matrix",
  "year": 1999,
  "poster": "https://example.com/matrix-poster.jpg",
  "banner": "https://example.com/matrix-banner.jpg",
  "description": "A computer hacker learns about the true nature of reality.",
  "rating": 8.7,
  "category": "Movie",
  "type": "Movie",
  "status": "Released",
  "aspectRatio": "2.39:1",
  "runtime": 136,
  "director": "The Wachowskis",
  "writer": "The Wachowskis",
  "releaseDate": "1999-03-31",
  "genres": ["Sci-Fi", "Action"],
  "tags": ["Cyberpunk", "AI", "Simulation"],
  "studios": ["Warner Bros."],
  "staff": [
    {
      "name": "Keanu Reeves",
      "photo": "https://example.com/keanu.jpg",
      "bio": "Canadian actor",
      "birthDate": "1964-09-02",
      "birthPlace": "Beirut, Lebanon",
      "role": "Actor",
      "characterName": "Neo",
      "characterImage": null,
      "occupations": ["Actor"]
    }
  ]
}
```

**Request Body (TV Series mit Episoden):**
```json
{
  "title": "Stranger Things",
  "year": 2016,
  "poster": "https://example.com/st-poster.jpg",
  "description": "When a young boy disappears, his mother uncovers a mystery.",
  "rating": 8.7,
  "category": "TV",
  "type": "TV",
  "status": "Ongoing",
  "runtime": 50,
  "director": "The Duffer Brothers",
  "writer": "The Duffer Brothers",
  "releaseDate": "2016-07-15",
  "genres": ["Sci-Fi", "Horror", "Drama"],
  "tags": ["80s", "Supernatural", "Government Conspiracy"],
  "studios": ["Netflix"],
  "staff": [],
  "episodes": [
    {
      "season": 1,
      "episode_number": 1,
      "title": "Chapter One: The Vanishing of Will Byers",
      "description": "On his way home from a friend's house, young Will sees something terrifying.",
      "air_date": "2016-07-15",
      "duration": 47,
      "thumbnail": "https://example.com/st-ep1.jpg"
    }
  ]
}
```

**Request Body (Album mit Tracks):**
```json
{
  "title": "Thriller",
  "year": 1982,
  "poster": "https://example.com/thriller-cover.jpg",
  "description": "Sixth studio album by Michael Jackson",
  "rating": 9.0,
  "category": "Music",
  "type": "Album",
  "status": "Released",
  "genres": ["Pop", "Funk", "Rock"],
  "tags": ["Classic", "Best-selling"],
  "studios": ["Epic Records"],
  "staff": [],
  "tracks": [
    {
      "track_number": 1,
      "title": "Wanna Be Startin' Somethin'",
      "duration": "6:03",
      "artist": "Michael Jackson"
    },
    {
      "track_number": 2,
      "title": "Baby Be Mine",
      "duration": "4:20",
      "artist": "Michael Jackson"
    }
  ]
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 4
  }
}
```

---

### PUT /api/media/:id
Medium aktualisieren. Nur die zu ändernden Felder übergeben.

**Request Body:**
```json
{
  "title": "The Matrix (Updated)",
  "rating": 8.8,
  "status": "Released"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

---

### DELETE /api/media/:id
Medium löschen.

**Beispiel Request:**
```
DELETE /api/media/1
```

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Media deleted successfully"
}
```

---

### GET /api/media/:id/episodes
Alle Episoden einer Serie abrufen.

**Query Parameter:**
- `season` - Nur Episoden einer bestimmten Staffel

**Beispiel Request:**
```
GET /api/media/2/episodes?season=1
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "media_id": 2,
        "season": 1,
        "episode_number": 1,
        "title": "Pilot",
        "description": "Walter White is diagnosed with lung cancer.",
        "air_date": "2008-01-20",
        "duration": 49,
        "thumbnail": "https://example.com/ep1.jpg"
      },
      {
        "id": 2,
        "media_id": 2,
        "season": 1,
        "episode_number": 2,
        "title": "Cat's in the Bag...",
        "description": "Walter and Jesse attempt to dispose of the body.",
        "air_date": "2008-01-27",
        "duration": 48,
        "thumbnail": "https://example.com/ep2.jpg"
      }
    ]
  }
}
```

---

### POST /api/media/:id/episodes
Neue Episode zu einer Serie hinzufügen.

**Request Body:**
```json
{
  "season": 1,
  "episode_number": 3,
  "title": "...And the Bag's in the River",
  "description": "Walter and Jesse deal with the aftermath.",
  "air_date": "2008-02-03",
  "duration": 47,
  "thumbnail": "https://example.com/ep3.jpg"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 3
  }
}
```

---

### PUT /api/media/:id/episodes/:episodeId
Episode aktualisieren.

**Request Body:**
```json
{
  "title": "Updated Episode Title",
  "description": "Updated description"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

---

### DELETE /api/media/:id/episodes/:episodeId
Episode löschen.

**Beispiel Request:**
```
DELETE /api/media/2/episodes/1
```

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Episode deleted successfully"
}
```

---

### GET /api/media/:id/tracks
Alle Tracks eines Albums abrufen.

**Beispiel Request:**
```
GET /api/media/3/tracks
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "media_id": 3,
        "track_number": 1,
        "title": "Speak to Me",
        "duration": "1:30",
        "artist": "Pink Floyd"
      },
      {
        "id": 2,
        "media_id": 3,
        "track_number": 2,
        "title": "Breathe",
        "duration": "2:43",
        "artist": "Pink Floyd"
      }
    ]
  }
}
```

---

### POST /api/media/:id/tracks
Neuen Track zu einem Album hinzufügen.

**Request Body:**
```json
{
  "track_number": 3,
  "title": "On the Run",
  "duration": "3:35",
  "artist": "Pink Floyd"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 3
  }
}
```

---

### PUT /api/media/:id/tracks/:trackId
Track aktualisieren.

**Request Body:**
```json
{
  "title": "Updated Track Title",
  "duration": "4:00"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

---

### DELETE /api/media/:id/tracks/:trackId
Track löschen.

**Beispiel Request:**
```
DELETE /api/media/3/tracks/1
```

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Track deleted successfully"
}
```

---

## CAST ENDPOINTS

### GET /api/cast
Alle Cast-Mitglieder abrufen mit Filterung und Pagination.

**Query Parameter:**
- `search` - Suche nach Name
- `page` - Seitennummer (Standard: 1)
- `limit` - Ergebnisse pro Seite (Standard: 20)

**Beispiel Request:**
```
GET /api/cast?search=Leonardo&page=1&limit=10
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Leonardo DiCaprio",
        "photo": "https://example.com/leo.jpg",
        "bio": "American actor and film producer",
        "birthDate": "1974-11-11",
        "birthPlace": "Los Angeles, California",
        "createdAt": "2024-01-15 10:30:00",
        "updatedAt": "2024-01-15 10:30:00"
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 10
  }
}
```

---

### GET /api/cast/:id
Ein einzelnes Cast-Mitglied abrufen mit Filmografie.

**Beispiel Request:**
```
GET /api/cast/1
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Leonardo DiCaprio",
    "photo": "https://example.com/leo.jpg",
    "bio": "American actor and film producer",
    "birthDate": "1974-11-11",
    "birthPlace": "Los Angeles, California",
    "createdAt": "2024-01-15 10:30:00",
    "updatedAt": "2024-01-15 10:30:00",
    "occupations": ["Actor", "Producer"],
    "filmography": [
      {
        "id": 1,
        "title": "Inception",
        "year": 2010,
        "poster": "https://example.com/poster.jpg",
        "category": "Movie",
        "type": "Movie",
        "role": "Actor",
        "characterName": "Dom Cobb"
      },
      {
        "id": 2,
        "title": "The Revenant",
        "year": 2015,
        "poster": "https://example.com/revenant.jpg",
        "category": "Movie",
        "type": "Movie",
        "role": "Actor",
        "characterName": "Hugh Glass"
      }
    ]
  }
}
```

---

### GET /api/cast/:id/media
Alle Medien eines Cast-Mitglieds abrufen.

**Beispiel Request:**
```
GET /api/cast/1/media
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Inception",
        "year": 2010,
        "poster": "https://example.com/poster.jpg",
        "category": "Movie",
        "type": "Movie",
        "role": "Actor",
        "characterName": "Dom Cobb"
      },
      {
        "id": 2,
        "title": "The Revenant",
        "year": 2015,
        "poster": "https://example.com/revenant.jpg",
        "category": "Movie",
        "type": "Movie",
        "role": "Actor",
        "characterName": "Hugh Glass"
      }
    ]
  }
}
```

---

### POST /api/cast
Neues Cast-Mitglied erstellen.

**Request Body:**
```json
{
  "name": "Tom Hardy",
  "photo": "https://example.com/tom.jpg",
  "bio": "English actor known for versatile roles",
  "birthDate": "1977-09-15",
  "birthPlace": "Hammersmith, London, England",
  "occupations": ["Actor", "Producer", "Writer"]
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 5
  }
}
```

---

### PUT /api/cast/:id
Cast-Mitglied aktualisieren. Nur die zu ändernden Felder übergeben.

**Request Body:**
```json
{
  "name": "Tom Hardy (Updated)",
  "bio": "Updated bio description"
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 5
  }
}
```

---

### DELETE /api/cast/:id
Cast-Mitglied löschen.

**Beispiel Request:**
```
DELETE /api/cast/1
```

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Cast member deleted successfully"
}
```

---

## ADULT CAST ENDPOINTS

### GET /api/cast/adult
Alle Adult-Cast-Mitglieder abrufen mit erweiterten Filtern.

**Query Parameter:**
- `search` - Suche nach Name
- `ethnicity` - Filter nach Ethnie
- `hair_color` - Filter nach Haarfarbe
- `page` - Seitennummer (Standard: 1)
- `limit` - Ergebnisse pro Seite (Standard: 20)

**Beispiel Request:**
```
GET /api/cast/adult?ethnicity=Caucasian&hair_color=Blonde&page=1&limit=10
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 10,
        "name": "Jane Doe",
        "photo": "https://example.com/jane.jpg",
        "bio": "Adult film actress",
        "birthDate": "1995-05-15",
        "birthPlace": "Los Angeles, California",
        "createdAt": "2024-01-15 10:30:00",
        "updatedAt": "2024-01-15 10:30:00",
        "occupations": ["Actress"],
        "bust_size": "34",
        "cup_size": "D",
        "waist_size": "24",
        "hip_size": "34",
        "height": "165",
        "weight": "52",
        "hair_color": "Blonde",
        "eye_color": "Blue",
        "ethnicity": "Caucasian"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 10
  }
}
```

---

### GET /api/cast/adult/:id
Ein einzelnes Adult-Cast-Mitglied abrufen mit allen Spezifikationen.

**Beispiel Request:**
```
GET /api/cast/adult/10
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 10,
    "name": "Jane Doe",
    "photo": "https://example.com/jane.jpg",
    "bio": "Adult film actress",
    "birthDate": "1995-05-15",
    "birthPlace": "Los Angeles, California",
    "createdAt": "2024-01-15 10:30:00",
    "updatedAt": "2024-01-15 10:30:00",
    "occupations": ["Actress"],
    "filmography": [],
    "adult_specifics": {
      "id": 5,
      "cast_id": 10,
      "bust_size": "34",
      "cup_size": "D",
      "waist_size": "24",
      "hip_size": "34",
      "height": "165",
      "weight": "52",
      "hair_color": "Blonde",
      "eye_color": "Blue",
      "ethnicity": "Caucasian",
      "tattoos": "None",
      "piercings": "Ears",
      "measurements": "34-24-34",
      "shoe_size": "7"
    }
  }
}
```

---

### POST /api/cast/adult
Neues Adult-Cast-Mitglied erstellen mit Spezifikationen.

**Request Body:**
```json
{
  "name": "Jane Smith",
  "photo": "https://example.com/jane-smith.jpg",
  "bio": "Adult film actress and model",
  "birthDate": "1998-03-20",
  "birthPlace": "Miami, Florida",
  "occupations": ["Actress", "Model"],
  "adult_specifics": {
    "bust_size": "36",
    "cup_size": "DD",
    "waist_size": "26",
    "hip_size": "38",
    "height": "170",
    "weight": "58",
    "hair_color": "Brunette",
    "eye_color": "Green",
    "ethnicity": "Latina",
    "tattoos": "Lower back",
    "piercings": "None",
    "measurements": "36-26-38",
    "shoe_size": "8"
  }
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 11
  }
}
```

---

### PUT /api/cast/adult/:id
Adult-Cast-Mitglied aktualisieren. Nur die zu ändernden Felder übergeben.

**Request Body:**
```json
{
  "name": "Jane Smith (Updated)",
  "bio": "Updated bio",
  "adult_specifics": {
    "hair_color": "Red",
    "weight": "56"
  }
}
```

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "id": 11
  }
}
```

---

### DELETE /api/cast/adult/:id
Adult-spezifische Daten löschen (nicht das Cast-Mitglied selbst).

**Beispiel Request:**
```
DELETE /api/cast/adult/10
```

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Adult specifics deleted successfully"
}
```

---

## ALLGEMEINE ENDPOINTS

### GET /api
API-Informationen und verfügbare Endpunkte.

**Beispiel Response:**
```json
{
  "success": true,
  "message": "Media API v1.0",
  "endpoints": {
    "GET /api/docs": "Automatische API-Dokumentation",
    "GET /api/media": "Alle Medien abrufen",
    "GET /api/media/:id": "Ein Medium abrufen",
    "POST /api/media": "Neues Medium erstellen",
    "PUT /api/media/:id": "Medium aktualisieren",
    "DELETE /api/media/:id": "Medium löschen",
    "GET /api/cast": "Alle Cast-Mitglieder abrufen",
    "GET /api/cast/:id": "Cast-Mitglied abrufen",
    "GET /api/cast/:id/media": "Alle Medien eines Cast-Mitglieds abrufen",
    "POST /api/cast": "Neues Cast-Mitglied erstellen",
    "PUT /api/cast/:id": "Cast-Mitglied aktualisieren",
    "DELETE /api/cast/:id": "Cast-Mitglied löschen"
  }
}
```

---

### GET /api/docs
Automatische API-Dokumentation.

**Beispiel Response:**
```json
{
  "success": true,
  "data": {
    "title": "Media API Documentation",
    "version": "1.0.0",
    "baseUrl": "/api",
    "endpoints": [...],
    "models": [...]
  }
}
```

---

## HINWEISE

1. **Content-Type**: Alle POST und PUT Requests müssen `Content-Type: application/json` Header haben.

2. **Pagination**: Bei Listen-Endpoints (GET ohne ID) werden standardmäßig 20 Ergebnisse pro Seite zurückgegeben.

3. **Filter**: Viele GET-Endpoints unterstützen Filter über Query-Parameter.

4. **Partial Updates**: Bei PUT-Endpoints müssen nur die zu ändernden Felder übergeben werden.

5. **Relationen**: Beim Erstellen können Relationen (Genres, Tags, Studios, Staff) direkt mitgegeben werden.

6. **Typ-spezifische Felder**: 
   - TV Series haben zusätzlich `episodes` Array
   - Alben haben zusätzlich `tracks` Array
   - Adult Cast haben zusätzlich `adult_specifics` Object

7. **Fehler-Response**:
```json
{
  "success": false,
  "error": "Fehlerbeschreibung"
}
```