mirror of
https://github.com/Dvorinka/ClubLogos.git
synced 2026-06-04 03:52:57 +00:00
Tomáš Dvořák
448 lines
9.3 KiB
Markdown
448 lines
9.3 KiB
Markdown
# 📡 API Usage Examples
|
|
|
|
Complete examples for using the Czech Clubs Logos API.
|
|
|
|
## 🔍 Search Clubs
|
|
|
|
### Basic Search
|
|
|
|
```bash
|
|
curl "http://localhost:8080/clubs/search?q=sparta"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "22222222-3333-4444-5555-666666666666",
|
|
"name": "AC Sparta Praha",
|
|
"city": "Praha",
|
|
"type": "football"
|
|
}
|
|
]
|
|
```
|
|
|
|
### JavaScript (Fetch)
|
|
|
|
```javascript
|
|
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
|
|
|
|
```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
|
|
|
|
```bash
|
|
curl "http://localhost:8080/clubs/22222222-3333-4444-5555-666666666666"
|
|
```
|
|
|
|
### JavaScript
|
|
|
|
```javascript
|
|
async function getClub(clubId) {
|
|
const response = await fetch(`http://localhost:8080/clubs/${clubId}`)
|
|
const club = await response.json()
|
|
return club
|
|
}
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
def get_club(club_id):
|
|
response = requests.get(f"http://localhost:8080/clubs/{club_id}")
|
|
return response.json()
|
|
```
|
|
|
|
## ⬆️ Upload Logo
|
|
|
|
### cURL
|
|
|
|
```bash
|
|
curl -X POST \
|
|
http://localhost:8080/logos/22222222-3333-4444-5555-666666666666 \
|
|
-F "file=@sparta.svg"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"id": "22222222-3333-4444-5555-666666666666",
|
|
"filename": "22222222-3333-4444-5555-666666666666.svg",
|
|
"size": 12345,
|
|
"message": "logo uploaded successfully"
|
|
}
|
|
```
|
|
|
|
### JavaScript (FormData)
|
|
|
|
```javascript
|
|
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
|
|
|
|
```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
|
|
|
|
```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
|
|
|
|
```bash
|
|
curl http://localhost:8080/logos/22222222-3333-4444-5555-666666666666 \
|
|
-o sparta.svg
|
|
```
|
|
|
|
### Display in HTML
|
|
|
|
```html
|
|
<img
|
|
src="http://localhost:8080/logos/22222222-3333-4444-5555-666666666666"
|
|
alt="AC Sparta Praha"
|
|
style="width: 100px; height: 100px;"
|
|
/>
|
|
```
|
|
|
|
### React Component
|
|
|
|
```jsx
|
|
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
|
|
|
|
```vue
|
|
<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
|
|
|
|
```bash
|
|
curl http://localhost:8080/logos/22222222-3333-4444-5555-666666666666/json
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```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
|
|
|
|
```javascript
|
|
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
|
|
|
|
```python
|
|
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`:
|
|
|
|
```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
|
|
|
|
```json
|
|
{
|
|
"error": "error message description"
|
|
}
|
|
```
|
|
|
|
### JavaScript Error Handling
|
|
|
|
```javascript
|
|
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](backend/README.md) for additional details!
|