API Endu

Wprowadzenie

API Endu umożliwia programistyczny dostęp do danych serwisu enduhub.com. API oparte jest na standardzie REST i zwraca dane w formacie JSON.

Autoryzacja

Aby korzystać z API, wymagany jest klucz dostępu (API key). Klucz dostępu wydawany jest po kontakcie z zespołem Endu.

Klucz API należy przekazywać w nagłówku żądania:

Authorization: Token YOUR_API_KEY

lub jako parametr:

?api_key=YOUR_API_KEY

Limitowanie zapytań

API posiada limity zapytań:

• Domyślny limit: 1000 żądań na godzinę na klucz API
• Limit dzienny: 10000 żądań na dzień

W przypadku przekroczenia limitu, API zwróci odpowiedź z kodem HTTP 429 (Too Many Requests).

Większe limity mogą być uzgodnione indywidualnie po kontakcie z zespołem.

Endpointy

Podstawowe informacje

• Base URL: https://enduhub.com/api/v1/
• Format odpowiedzi: JSON
• Kodowanie: UTF-8

Przykładowe endpointy

Pobieranie wyników zawodów

GET /api/v1/results/{id}/

Zwraca szczegóły konkretnego wyniku zawodów.

Przykład odpowiedzi:

{
  "id": 12345,
  "event": "Maraton Warszawski 2024",
  "user": "jan.kowalski",
  "time": "03:45:23",
  "position": 42,
  "category": "M30-39",
  "date": "2024-09-15"
}

Pobieranie profilu użytkownika

GET /api/v1/users/{username}/

Zwraca publiczne informacje o użytkowniku.

Przykład odpowiedzi:

{
  "username": "jan.kowalski",
  "first_name": "Jan",
  "last_name": "Kowalski",
  "country": "PL",
  "city": "Warszawa",
  "results_count": 156,
  "profile_url": "https://enduhub.com/users/jan.kowalski/"
}

Lista wyników użytkownika

GET /api/v1/users/{username}/results/

Zwraca listę wyników danego użytkownika.

Parametry opcjonalne:

• limit - liczba wyników (domyślnie 20, maksimum 100)
• offset - przesunięcie dla paginacji
• event - filtrowanie po nazwie wydarzenia
• year - filtrowanie po roku

Kody odpowiedzi HTTP

• 200 OK - żądanie zakończone sukcesem
• 400 Bad Request - nieprawidłowe parametry żądania
• 401 Unauthorized - brak lub nieprawidłowy klucz API
• 403 Forbidden - brak uprawnień do zasobu
• 404 Not Found - zasób nie został znaleziony
• 429 Too Many Requests - przekroczony limit zapytań
• 500 Internal Server Error - błąd serwera

Przykłady użycia

cURL

curl -H "Authorization: Token YOUR_API_KEY" \
     https://enduhub.com/api/v1/results/12345/

Python

import requests

headers = {
    'Authorization': 'Token YOUR_API_KEY'
}

response = requests.get(
    'https://enduhub.com/api/v1/results/12345/',
    headers=headers
)

data = response.json()
print(data)

JavaScript

fetch('https://enduhub.com/api/v1/results/12345/', {
  headers: {
    'Authorization': 'Token YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Wersjonowanie

Obecna wersja API to v1. W przyszłości mogą pojawić się nowe wersje, które będą dostępne pod innymi ścieżkami (np. /api/v2/).

Wsparcie techniczne

W sprawach dotyczących API, w tym:
- uzyskania klucza dostępu,
- zwiększenia limitów,
- zgłaszania problemów,
- propozycji nowych funkcji,

prosimy o kontakt:

• Formularz kontaktowy: https://enduhub.com/pl/kontakt/

Dokumentacja szczegółowa

Pełna dokumentacja API z wszystkimi dostępnymi endpointami dostępna jest po zalogowaniu w panelu deweloperskim: https://enduhub.com/api/docs/

Warunki użytkowania

Korzystanie z API podlega warunkom określonym w Regulaminie serwisu oraz niniejszej dokumentacji. W szczególności:

• Dane pobrane z API nie mogą być wykorzystywane w sposób naruszający prawa autorskie
• Zabronione jest automatyczne pobieranie dużych ilości danych bez uzgodnienia z administratorem
• API nie może być wykorzystywane do celów komercyjnych bez wcześniejszej zgody