ClubLogos/API_EXAMPLES.md

📡 API Usage Examples

Complete examples for using the Czech Clubs Logos API.

🔍 Search Clubs

Basic Search

curl "http://localhost:8080/clubs/search?q=sparta"

Response:

[
  {
    "id": "22222222-3333-4444-5555-666666666666",
    "name": "AC Sparta Praha",
    "city": "Praha",
    "type": "football"
  }
]

JavaScript (Fetch)

async function searchClubs(query) {
  const response = await fetch(`http://localhost:8080/clubs/search?q=${query}`)
  const clubs = await response.json()
  console.log(clubs)
  return clubs
}

searchClubs('slavia')

Python

import requests

def search_clubs(query):
    response = requests.get(f"http://localhost:8080/clubs/search?q={query}")
    return response.json()

clubs = search_clubs('sparta')
print(clubs)

🏆 Get Club Details

cURL

curl "http://localhost:8080/clubs/22222222-3333-4444-5555-666666666666"

JavaScript

async function getClub(clubId) {
  const response = await fetch(`http://localhost:8080/clubs/${clubId}`)
  const club = await response.json()
  return club
}

Python

def get_club(club_id):
    response = requests.get(f"http://localhost:8080/clubs/{club_id}")
    return response.json()

⬆️ Upload Logo

cURL

curl -X POST \
  http://localhost:8080/logos/22222222-3333-4444-5555-666666666666 \
  -F "file=@sparta.svg"

Response:

{
  "success": true,
  "id": "22222222-3333-4444-5555-666666666666",
  "filename": "22222222-3333-4444-5555-666666666666.svg",
  "size": 12345,
  "message": "logo uploaded successfully"
}

JavaScript (FormData)

async function uploadLogo(clubId, file) {
  const formData = new FormData()
  formData.append('file', file)
  
  const response = await fetch(`http://localhost:8080/logos/${clubId}`, {
    method: 'POST',
    body: formData
  })
  
  return await response.json()
}

// Usage with file input
const fileInput = document.getElementById('fileInput')
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0]
  const clubId = '22222222-3333-4444-5555-666666666666'
  const result = await uploadLogo(clubId, file)
  console.log(result)
})

Python

def upload_logo(club_id, file_path):
    with open(file_path, 'rb') as f:
        files = {'file': f}
        response = requests.post(
            f"http://localhost:8080/logos/{club_id}",
            files=files
        )
    return response.json()

result = upload_logo(
    '22222222-3333-4444-5555-666666666666',
    'sparta.svg'
)
print(result)

PowerShell

$clubId = "22222222-3333-4444-5555-666666666666"
$filePath = "C:\logos\sparta.svg"

$form = @{
    file = Get-Item -Path $filePath
}

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

🖼️ Get Logo

Download Logo

curl http://localhost:8080/logos/22222222-3333-4444-5555-666666666666 \
  -o sparta.svg

Display in HTML

<img 
  src="http://localhost:8080/logos/22222222-3333-4444-5555-666666666666" 
  alt="AC Sparta Praha"
  style="width: 100px; height: 100px;"
/>

React Component

function ClubLogo({ clubId, clubName }) {
  const logoUrl = `http://localhost:8080/logos/${clubId}`
  
  return (
    <img 
      src={logoUrl}
      alt={clubName}
      className="club-logo"
      onError={(e) => {
        e.target.src = '/fallback-logo.svg'
      }}
    />
  )
}

Vue Component

<template>
  <img 
    :src="logoUrl" 
    :alt="clubName"
    class="club-logo"
    @error="handleError"
  />
</template>

<script setup>
import { computed } from 'vue'

const props = defineProps(['clubId', 'clubName'])

const logoUrl = computed(() => 
  `http://localhost:8080/logos/${props.clubId}`
)

function handleError(e) {
  e.target.src = '/fallback-logo.svg'
}
</script>

📋 Get Logo with Metadata

cURL

curl http://localhost:8080/logos/22222222-3333-4444-5555-666666666666/json

Response:

{
  "id": "22222222-3333-4444-5555-666666666666",
  "club_name": "AC Sparta Praha",
  "club_city": "Praha",
  "club_type": "football",
  "logo_url": "http://localhost:8080/logos/22222222-3333-4444-5555-666666666666",
  "file_size": 12345,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

JavaScript

async function getLogoMetadata(clubId) {
  const response = await fetch(`http://localhost:8080/logos/${clubId}/json`)
  const metadata = await response.json()
  return metadata
}

🔄 Complete Workflow Example

JavaScript Full Example

class CzechClubsAPI {
  constructor(baseUrl = 'http://localhost:8080') {
    this.baseUrl = baseUrl
  }
  
  async searchClubs(query) {
    const response = await fetch(`${this.baseUrl}/clubs/search?q=${query}`)
    return await response.json()
  }
  
  async getClub(clubId) {
    const response = await fetch(`${this.baseUrl}/clubs/${clubId}`)
    return await response.json()
  }
  
  async uploadLogo(clubId, file) {
    const formData = new FormData()
    formData.append('file', file)
    
    const response = await fetch(`${this.baseUrl}/logos/${clubId}`, {
      method: 'POST',
      body: formData
    })
    
    return await response.json()
  }
  
  getLogoUrl(clubId) {
    return `${this.baseUrl}/logos/${clubId}`
  }
  
  async getLogoMetadata(clubId) {
    const response = await fetch(`${this.baseUrl}/logos/${clubId}/json`)
    return await response.json()
  }
}

// Usage
const api = new CzechClubsAPI()

// Search and upload
async function uploadClubLogo() {
  // 1. Search for club
  const clubs = await api.searchClubs('sparta')
  const spartaClub = clubs[0]
  
  console.log('Found club:', spartaClub)
  
  // 2. Get file from user
  const fileInput = document.querySelector('input[type="file"]')
  const file = fileInput.files[0]
  
  // 3. Upload logo
  const result = await api.uploadLogo(spartaClub.id, file)
  console.log('Upload result:', result)
  
  // 4. Get logo URL
  const logoUrl = api.getLogoUrl(spartaClub.id)
  console.log('Logo URL:', logoUrl)
  
  // 5. Display logo
  document.querySelector('img').src = logoUrl
}

Python Full Example

import requests
from typing import List, Dict, Optional

class CzechClubsAPI:
    def __init__(self, base_url: str = "http://localhost:8080"):
        self.base_url = base_url
    
    def search_clubs(self, query: str) -> List[Dict]:
        response = requests.get(f"{self.base_url}/clubs/search?q={query}")
        response.raise_for_status()
        return response.json()
    
    def get_club(self, club_id: str) -> Dict:
        response = requests.get(f"{self.base_url}/clubs/{club_id}")
        response.raise_for_status()
        return response.json()
    
    def upload_logo(self, club_id: str, file_path: str) -> Dict:
        with open(file_path, 'rb') as f:
            files = {'file': f}
            response = requests.post(
                f"{self.base_url}/logos/{club_id}",
                files=files
            )
        response.raise_for_status()
        return response.json()
    
    def get_logo_url(self, club_id: str) -> str:
        return f"{self.base_url}/logos/{club_id}"
    
    def get_logo_metadata(self, club_id: str) -> Dict:
        response = requests.get(f"{self.base_url}/logos/{club_id}/json")
        response.raise_for_status()
        return response.json()
    
    def download_logo(self, club_id: str, output_path: str):
        response = requests.get(self.get_logo_url(club_id))
        response.raise_for_status()
        
        with open(output_path, 'wb') as f:
            f.write(response.content)

# Usage
api = CzechClubsAPI()

# Search for clubs
clubs = api.search_clubs("sparta")
print(f"Found {len(clubs)} clubs")

# Get first club
sparta = clubs[0]
print(f"Club: {sparta['name']}")

# Upload logo
result = api.upload_logo(sparta['id'], 'sparta.svg')
print(f"Upload: {result['message']}")

# Download logo
api.download_logo(sparta['id'], 'downloaded_sparta.svg')
print("Logo downloaded!")

# Get metadata
metadata = api.get_logo_metadata(sparta['id'])
print(f"File size: {metadata['file_size']} bytes")

🌐 CORS Configuration

The API has CORS enabled. You can make requests from any origin in development.

For production, configure allowed origins in backend/main.go:

r.Use(cors.New(cors.Config{
    AllowOrigins: []string{"https://yourdomain.com"},
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
}))

🔒 Error Handling

Common HTTP Status Codes

Code	Meaning	Example
200	Success	Request completed
400	Bad Request	Invalid UUID format
404	Not Found	Logo doesn't exist
500	Server Error	Database issue

Error Response Format

{
  "error": "error message description"
}

JavaScript Error Handling

async function safeGetLogo(clubId) {
  try {
    const response = await fetch(`http://localhost:8080/logos/${clubId}/json`)
    
    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.error || 'Request failed')
    }
    
    return await response.json()
  } catch (error) {
    console.error('Failed to get logo:', error.message)
    return null
  }
}

---

Need more examples? Check out the backend/README.md for additional details!