Ceratic/mystuff_backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66f69bc90ddffad30c6738be6643792d526eb3b1
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

1036 lines
20 KiB
Markdown
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:**
```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"
}
```
Reference in New Issue View Git Blame Copy Permalink