Ceratic/mystuff_backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eeff82470177eccf55daa5a5505ba7c046897dff
mystuff_backend/API_EXAMPLES.md
Lars Behrends 66f69bc90d Add PHP Media API scaffold and Docker configs 
Initial project scaffold for a PHP Media API including routing, controllers, models and services under api/ (Router, Media/Cast/Image/Settings controllers, models, database/bootstrap files and automatic docs service). Adds Docker support (Dockerfile, docker-compose.yml, DOCKER_README.md, php-custom.ini), .htaccess for pretty URLs, API documentation and example payloads (API_EXAMPLES.md, api/README.md, api_examples/*.json), image handling service and logging, plus a comprehensive .gitignore. This commit provides a runnable development environment and example requests to get the API up and tested quickly.
2026-04-12 00:46:30 +02:00

20 KiB
Raw Blame History

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:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "success": true,
  "data": {
    "id": 4
  }
}

PUT /api/media/:id

Medium aktualisieren. Nur die zu ändernden Felder übergeben.

Request Body:

{
  "title": "The Matrix (Updated)",
  "rating": 8.8,
  "status": "Released"
}

Beispiel Response:

{
  "success": true,
  "data": {
    "id": 1
  }
}

DELETE /api/media/:id

Medium löschen.

Beispiel Request:

DELETE /api/media/1

Beispiel Response:

{
  "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:

{
  "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:

{
  "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:

{
  "success": true,
  "data": {
    "id": 3
  }
}

PUT /api/media/:id/episodes/:episodeId

Episode aktualisieren.

Request Body:

{
  "title": "Updated Episode Title",
  "description": "Updated description"
}

Beispiel Response:

{
  "success": true,
  "data": {
    "id": 1
  }
}

DELETE /api/media/:id/episodes/:episodeId

Episode löschen.

Beispiel Request:

DELETE /api/media/2/episodes/1

Beispiel Response:

{
  "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:

{
  "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:

{
  "track_number": 3,
  "title": "On the Run",
  "duration": "3:35",
  "artist": "Pink Floyd"
}

Beispiel Response:

{
  "success": true,
  "data": {
    "id": 3
  }
}

PUT /api/media/:id/tracks/:trackId

Track aktualisieren.

Request Body:

{
  "title": "Updated Track Title",
  "duration": "4:00"
}

Beispiel Response:

{
  "success": true,
  "data": {
    "id": 1
  }
}

DELETE /api/media/:id/tracks/:trackId

Track löschen.

Beispiel Request:

DELETE /api/media/3/tracks/1

Beispiel Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "success": true,
  "data": {
    "id": 5
  }
}

PUT /api/cast/:id

Cast-Mitglied aktualisieren. Nur die zu ändernden Felder übergeben.

Request Body:

{
  "name": "Tom Hardy (Updated)",
  "bio": "Updated bio description"
}

Beispiel Response:

{
  "success": true,
  "data": {
    "id": 5
  }
}

DELETE /api/cast/:id

Cast-Mitglied löschen.

Beispiel Request:

DELETE /api/cast/1

Beispiel Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "success": true,
  "data": {
    "id": 11
  }
}

PUT /api/cast/adult/:id

Adult-Cast-Mitglied aktualisieren. Nur die zu ändernden Felder übergeben.

Request Body:

{
  "name": "Jane Smith (Updated)",
  "bio": "Updated bio",
  "adult_specifics": {
    "hair_color": "Red",
    "weight": "56"
  }
}

Beispiel Response:

{
  "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:

{
  "success": true,
  "message": "Adult specifics deleted successfully"
}

ALLGEMEINE ENDPOINTS

GET /api

API-Informationen und verfügbare Endpunkte.

Beispiel Response:

{
  "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:

{
  "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:

{
  "success": false,
  "error": "Fehlerbeschreibung"
}
Reference in New Issue View Git Blame Copy Permalink