API Dokumentace - České Kluby Loga API

🚀 Rychlý Start

⬆️ Nahrání loga klubu - Základní příkaz

curl -X POST http://localhost:8080/logos/{club-uuid} \
  -F "file=@logo.svg" \
  -F "club_name=Název Klubu"

Povinné: Club UUID v URL, soubor loga (SVG/PNG/PDF), název klubu

Volitelné: club_type, club_website, club_city

📥 Stažení loga klubu

# Přímo z backendu
curl http://localhost:8080/logos/{uuid}

# Přes frontend proxy
curl http://localhost:3000/api/logos/{uuid}

Vrátí PNG obrázek loga (SVG jako fallback)

📡 Endpointy

GET /logos

Seznam všech nahraných log

Response 200:

[
  {
    "id": "uuid-here",
    "club_name": "AC Sparta Praha",
    "club_type": "football",
    "has_svg": true,
    "has_png": true,
    "logo_url": "http://localhost:8080/logos/uuid-here",
    "created_at": "2024-01-01T12:00:00Z"
  }
]

GET /logos/:id

Získání souboru loga (PNG preferováno, SVG jako fallback)

Query Parameters (volitelné):

format string - "png" nebo "svg"

Response 200:

Binární data obrázku (image/png nebo image/svg+xml)

GET /logos/:id/json

Získání metadat loga ve formátu JSON

Response 200:

{
  "id": "uuid-here",
  "club_name": "AC Sparta Praha",
  "club_type": "football",
  "club_website": "https://sparta.cz",
  "has_svg": true,
  "has_png": true,
  "primary_format": "png",
  "logo_url": "http://localhost:8080/logos/uuid-here",
  "logo_url_svg": "http://localhost:8080/logos/uuid-here?format=svg",
  "logo_url_png": "http://localhost:8080/logos/uuid-here?format=png",
  "file_size_svg": 12345,
  "file_size_png": 54321,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

POST /logos/:id

Nahrání nového loga klubu s kompletními daty (ID klubu, název, logo soubory)

URL Parameters:

:id * UUID - Jedinečné ID klubu (např. 550e8400-e29b-41d4-a716-446655440000)

Content-Type:

multipart/form-data

Form Data (Povinné pole):

file * file (SVG nebo PNG)

Soubor loga. Podporované formáty: SVG (doporučeno), PNG, PDF

club_name * string

Název klubu (např. "AC Sparta Praha")

Form Data (Volitelné):

club_type string

Typ klubu: "football" (výchozí) nebo "futsal"

club_website string

URL webové stránky klubu (např. "https://sparta.cz")

club_city string

Město klubu (např. "Praha")

Response 200 (Úspěch):

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "club_name": "AC Sparta Praha",
  "has_svg": true,
  "has_png": true,
  "size_svg": 12543,
  "size_png": 45210,
  "message": "logo uploaded successfully"
}

Response 400 (Chyba):

{
  "error": "club_name is required"
}

Možné chyby: "no file provided", "invalid UUID format", "only .svg, .png and .pdf files are allowed"

💡 Příklady Použití - Nahrání Loga

🔧 cURL (Terminal)

Minimální nahrání (pouze povinná pole):

curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
  -F "file=@sparta_logo.svg" \
  -F "club_name=AC Sparta Praha"

Kompletní nahrání (všechna data):

curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
  -F "file=@sparta_logo.svg" \
  -F "club_name=AC Sparta Praha" \
  -F "club_type=football" \
  -F "club_website=https://sparta.cz" \
  -F "club_city=Praha"

Nahrání PNG místo SVG:

curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
  -F "file=@sparta_logo.png" \
  -F "club_name=AC Sparta Praha"

📜 JavaScript (Fetch API)

// Funkce pro nahrání loga s kompletními daty
async function uploadClubLogo(clubId, file, clubData) {
  const formData = new FormData();
  
  // Povinná pole
  formData.append('file', file);
  formData.append('club_name', clubData.name);
  
  // Volitelná pole
  if (clubData.type) formData.append('club_type', clubData.type);
  if (clubData.website) formData.append('club_website', clubData.website);
  if (clubData.city) formData.append('club_city', clubData.city);
  
  const response = await fetch(`http://localhost:8080/logos/${clubId}`, {
    method: 'POST',
    body: formData
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }
  
  return await response.json();
}

// Použití s file input
const fileInput = document.getElementById('logoFile');
const clubId = '550e8400-e29b-41d4-a716-446655440000';

const result = await uploadClubLogo(clubId, fileInput.files[0], {
  name: 'AC Sparta Praha',
  type: 'football',
  website: 'https://sparta.cz',
  city: 'Praha'
});

console.log('Upload successful:', result);

🐍 Python (requests)

import requests

def upload_club_logo(club_id, file_path, club_name, **optional_data):
    """
    Nahraje logo klubu s kompletními daty
    
    Args:
        club_id: UUID klubu
        file_path: Cesta k souboru loga
        club_name: Název klubu (povinný)
        **optional_data: club_type, club_website, club_city
    """
    with open(file_path, 'rb') as f:
        files = {'file': f}
        data = {'club_name': club_name}
        data.update(optional_data)
        
        response = requests.post(
            f"http://localhost:8080/logos/{club_id}",
            files=files,
            data=data
        )
        response.raise_for_status()
        return response.json()

# Použití
result = upload_club_logo(
    club_id='550e8400-e29b-41d4-a716-446655440000',
    file_path='sparta_logo.svg',
    club_name='AC Sparta Praha',
    club_type='football',
    club_website='https://sparta.cz',
    club_city='Praha'
)

print(f"Upload úspěšný: {result['message']}")
print(f"Has SVG: {result['has_svg']}, Has PNG: {result['has_png']}")

💻 PowerShell

# Nahrání loga s kompletními daty
$clubId = "550e8400-e29b-41d4-a716-446655440000"
$logoFile = "C:\logos\sparta_logo.svg"

$form = @{
    file = Get-Item -Path $logoFile
    club_name = "AC Sparta Praha"
    club_type = "football"
    club_website = "https://sparta.cz"
    club_city = "Praha"
}

$result = Invoke-RestMethod `
    -Uri "http://localhost:8080/logos/$clubId" `
    -Method Post `
    -Form $form

Write-Host "Upload úspěšný: $($result.message)" -ForegroundColor Green
Write-Host "Club: $($result.club_name)" -ForegroundColor Cyan

⚠️ Chybové Kódy

200

OK

Požadavek úspěšně dokončen

400

Bad Request

Neplatné parametry nebo chybějící povinná pole

404

Not Found

Logo nebo klub nenalezen

500

Internal Server Error

Interní chyba serveru