reptil1990/Ninjaserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c347ddb7b4f3fdca771017d1fd6a6a18decbc57a
Ninjaserver/API.md
Carsten Graf c347ddb7b4 📚 Add comprehensive API documentation 
- Created detailed API.md with all endpoints
- Documented Public, Private, Web, Admin and Achievements APIs
- Added request/response examples for all routes
- Included data models and error handling
- Added authentication methods and status codes
- Comprehensive documentation for 55+ API endpoints
2025-09-08 17:33:23 +02:00

13 KiB
Raw Blame History

🏃‍♂️ Ninja Cross Parkour API Dokumentation

Version: 1.0.0
Base URL: https://ninja.reptilfpv.de
Beschreibung: API für das Ninja Cross Parkour System im Schwimmbad

📋 Inhaltsverzeichnis

🔐 Authentifizierung

API-Key Authentifizierung

Für private Endpoints wird ein API-Key im Authorization Header benötigt:

Authorization: Bearer YOUR_API_KEY_HERE

Session-basierte Authentifizierung

Für Web-Endpoints wird eine Session-basierte Authentifizierung verwendet.

Admin-Authentifizierung

Für Admin-Endpoints wird eine erweiterte Authentifizierung mit Admin-Rechten benötigt.

🌐 Public API

Öffentliche Endpoints ohne Authentifizierung.

🔑 Authentifizierung

Login

POST /api/v1/public/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

Response:

{
  "success": true,
  "message": "Login erfolgreich",
  "user": {
    "id": 1,
    "username": "admin",
    "is_active": true
  }
}

Logout

POST /api/v1/public/logout

Response:

{
  "success": true,
  "message": "Logout erfolgreich"
}

👥 Spieler Management

Spieler erstellen

POST /api/v1/public/players
Content-Type: application/json

{
  "firstname": "Max",
  "lastname": "Mustermann",
  "birthdate": "1990-01-01",
  "rfiduid": "AA:BB:CC:DD"
}

Spieler verknüpfen

POST /api/v1/public/link-player
Content-Type: application/json

{
  "rfiduid": "AA:BB:CC:DD",
  "supabase_user_id": "uuid-here"
}

Spieler per RFID verknüpfen

POST /api/v1/public/link-by-rfid
Content-Type: application/json

{
  "rfiduid": "AA:BB:CC:DD",
  "supabase_user_id": "uuid-here"
}

📍 Standorte

Alle Standorte abrufen

GET /api/v1/public/locations

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Standort 1",
      "latitude": 48.1351,
      "longitude": 11.5820,
      "time_threshold": {
        "seconds": 120
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

⏱️ Zeiten

Alle Zeiten abrufen

GET /api/v1/public/times

Zeiten mit Details abrufen

GET /api/v1/public/times-with-details

Beste Zeiten abrufen

GET /api/v1/public/best-times

Benutzer-Zeiten abrufen

GET /api/v1/public/user-times/{supabase_user_id}

Benutzer-Spieler abrufen

GET /api/v1/public/user-player/{supabase_user_id}

📊 Statistiken

Seitenaufruf verfolgen

POST /api/v1/public/track-page-view
Content-Type: application/json

{
  "page": "/dashboard",
  "user_agent": "Mozilla/5.0...",
  "ip_address": "192.168.1.1"
}

🔔 Push Notifications

Push-Benachrichtigung abonnieren

POST /api/v1/public/subscribe
Content-Type: application/json

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "key-here",
    "auth": "auth-key-here"
  }
}

Push-Benachrichtigung testen

POST /api/v1/public/test-push
Content-Type: application/json

{
  "title": "Test",
  "body": "Test-Nachricht",
  "icon": "/icon.png"
}

Push-Status abrufen

GET /api/v1/public/push-status

🔒 Private API

Private Endpoints mit API-Key Authentifizierung.

🎫 Token Management

Token speichern

POST /api/v1/private/save-token
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "token": "GENERATED_TOKEN",
  "description": "Beschreibung",
  "standorte": "München, Berlin"
}

Alle Token abrufen

GET /api/v1/private/tokens
Authorization: Bearer YOUR_API_KEY

Token validieren

POST /api/v1/private/validate-token
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "token": "TOKEN_TO_VALIDATE"
}

📍 Standort Management

Standort erstellen

POST /api/v1/private/create-location
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "München",
  "latitude": 48.1351,
  "longitude": 11.5820
}

Alle Standorte abrufen

GET /api/v1/private/locations
Authorization: Bearer YOUR_API_KEY

Standort-Schwelle aktualisieren

PUT /api/v1/private/locations/{id}/threshold
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "threshold_seconds": 120
}

Standorte abrufen (Alternative)

GET /api/v1/private/get-locations
Authorization: Bearer YOUR_API_KEY

👥 Spieler Management

Spieler erstellen

POST /api/v1/private/create-player
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "firstname": "Max",
  "lastname": "Mustermann",
  "birthdate": "1990-01-01",
  "rfiduid": "AA:BB:CC:DD"
}

Benutzer suchen

POST /api/v1/private/users/find
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "search_term": "Max"
}

⏱️ Zeit Management

Zeit erstellen

POST /api/v1/private/create-time
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "player_id": "uuid",
  "location_id": "uuid",
  "recorded_time": "01:23.456"
}

🖥️ Web API

Web-API-Endpoints für das Frontend.

🔑 API-Key generieren

POST /api/v1/web/generate-api-key
Content-Type: application/json

{
  "description": "Mein API Key",
  "standorte": "München, Berlin"
}

📍 Standort erstellen

POST /api/v1/web/create-location
Content-Type: application/json

{
  "name": "München",
  "latitude": 48.1351,
  "longitude": 11.5820
}

🎫 Token speichern

POST /api/v1/web/save-token
Content-Type: application/json

{
  "token": "GENERATED_TOKEN",
  "description": "Beschreibung",
  "standorte": "München, Berlin"
}

🔍 Session prüfen

GET /api/v1/web/check-session

👑 Admin API

Admin-API-Endpoints für Verwaltung.

📊 Statistiken

Admin-Statistiken

GET /api/v1/admin/stats
Authorization: Bearer ADMIN_TOKEN

Seiten-Statistiken

GET /api/v1/admin/page-stats
Authorization: Bearer ADMIN_TOKEN

👥 Spieler Verwaltung

Alle Spieler abrufen

GET /api/v1/admin/players
Authorization: Bearer ADMIN_TOKEN

Spieler erstellen

POST /api/v1/admin/players
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "firstname": "Max",
  "lastname": "Mustermann",
  "birthdate": "1990-01-01",
  "rfiduid": "AA:BB:CC:DD"
}

Spieler aktualisieren

PUT /api/v1/admin/players/{id}
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "firstname": "Max",
  "lastname": "Mustermann",
  "birthdate": "1990-01-01",
  "rfiduid": "AA:BB:CC:DD"
}

Spieler löschen

DELETE /api/v1/admin/players/{id}
Authorization: Bearer ADMIN_TOKEN

🏃‍♂️ Läufe Verwaltung

Alle Läufe abrufen

GET /api/v1/admin/runs
Authorization: Bearer ADMIN_TOKEN

Lauf abrufen

GET /api/v1/admin/runs/{id}
Authorization: Bearer ADMIN_TOKEN

Lauf erstellen

POST /api/v1/admin/runs
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "player_id": "uuid",
  "location_id": "uuid",
  "recorded_time": "01:23.456"
}

Lauf aktualisieren

PUT /api/v1/admin/runs/{id}
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "recorded_time": "01:20.000"
}

Lauf löschen

DELETE /api/v1/admin/runs/{id}
Authorization: Bearer ADMIN_TOKEN

📍 Standort Verwaltung

Alle Standorte abrufen

GET /api/v1/admin/locations
Authorization: Bearer ADMIN_TOKEN

Standort erstellen

POST /api/v1/admin/locations
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "name": "München",
  "latitude": 48.1351,
  "longitude": 11.5820,
  "time_threshold": 120
}

Standort aktualisieren

PUT /api/v1/admin/locations/{id}
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "name": "München Updated",
  "latitude": 48.1351,
  "longitude": 11.5820,
  "time_threshold": 120
}

Standort löschen

DELETE /api/v1/admin/locations/{id}
Authorization: Bearer ADMIN_TOKEN

👤 Admin-Benutzer Verwaltung

Alle Admin-Benutzer abrufen

GET /api/v1/admin/adminusers
Authorization: Bearer ADMIN_TOKEN

Admin-Benutzer erstellen

POST /api/v1/admin/adminusers
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "username": "newadmin",
  "password": "securepassword"
}

Admin-Benutzer aktualisieren

PUT /api/v1/admin/adminusers/{id}
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "username": "updatedadmin",
  "is_active": true
}

Admin-Benutzer löschen

DELETE /api/v1/admin/adminusers/{id}
Authorization: Bearer ADMIN_TOKEN

🏆 Achievements API

Achievement-System Endpoints.

🏆 Achievements abrufen

GET /api/achievements

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Erster Lauf",
      "description": "Absolviere deinen ersten Lauf",
      "category": "consistency",
      "condition_type": "runs_count",
      "condition_value": 1,
      "icon": "🏃‍♂️",
      "points": 10,
      "is_active": true
    }
  ]
}

👤 Spieler-Achievements

GET /api/achievements/player/{playerId}

📊 Spieler-Statistiken

GET /api/achievements/player/{playerId}/stats

✅ Achievement prüfen

POST /api/achievements/check/{playerId}
Content-Type: application/json

{
  "achievement_id": "uuid"
}

📅 Tägliche Prüfung

POST /api/achievements/daily-check

🏃‍♂️ Beste Zeit prüfen

POST /api/achievements/best-time-check

🏅 Leaderboard

GET /api/achievements/leaderboard

📊 Datenmodelle

Player

{
  "id": "string (uuid)",
  "firstname": "string",
  "lastname": "string",
  "birthdate": "string (date)",
  "rfiduid": "string (XX:XX:XX:XX)",
  "supabase_user_id": "string (uuid)",
  "created_at": "string (date-time)"
}

Time

{
  "id": "string (uuid)",
  "player_id": "string (uuid)",
  "location_id": "string (uuid)",
  "recorded_time": {
    "seconds": "number",
    "minutes": "number",
    "milliseconds": "number"
  },
  "created_at": "string (date-time)"
}

Location

{
  "id": "string (uuid)",
  "name": "string",
  "latitude": "number (float)",
  "longitude": "number (float)",
  "time_threshold": {
    "seconds": "number",
    "minutes": "number"
  },
  "created_at": "string (date-time)"
}

Achievement

{
  "id": "string (uuid)",
  "name": "string",
  "description": "string",
  "category": "string (consistency|improvement|seasonal|monthly)",
  "condition_type": "string",
  "condition_value": "integer",
  "icon": "string (emoji)",
  "points": "integer",
  "is_active": "boolean"
}

PlayerAchievement

{
  "id": "string (uuid)",
  "player_id": "string (uuid)",
  "achievement_id": "string (uuid)",
  "progress": "integer",
  "is_completed": "boolean",
  "earned_at": "string (date-time)"
}

❌ Fehlerbehandlung

Standard-Fehlerantwort

{
  "success": false,
  "message": "Fehlermeldung",
  "error": "DETAILED_ERROR_INFO"
}

HTTP-Status-Codes

  • 200 OK - Erfolgreiche Anfrage
  • 201 Created - Ressource erfolgreich erstellt
  • 400 Bad Request - Ungültige Anfrage
  • 401 Unauthorized - Nicht authentifiziert
  • 403 Forbidden - Keine Berechtigung
  • 404 Not Found - Ressource nicht gefunden
  • 500 Internal Server Error - Serverfehler

Häufige Fehlermeldungen

  • "API-Key erforderlich" - Fehlender oder ungültiger API-Key
  • "Ungültige Anmeldedaten" - Falsche Login-Daten
  • "Ressource nicht gefunden" - Angeforderte Ressource existiert nicht
  • "Ungültige Daten" - Validierungsfehler bei Eingabedaten
  • "Keine Berechtigung" - Unzureichende Rechte für die Aktion

🔧 Entwicklung

Lokale Entwicklung

# Server starten
npm run dev

# API-Dokumentation anzeigen
# Swagger UI verfügbar unter: http://localhost:3000/api-docs

Produktionsumgebung

# Server starten
npm start

# API-Dokumentation: https://ninja.reptilfpv.de/api-docs

📝 Changelog

Version 1.0.0

  • Initiale API-Implementierung
  • Public, Private, Web und Admin Endpoints
  • Achievement-System
  • Push-Notification Support
  • Swagger-Dokumentation

👨‍💻 Autor

Carsten Graf
Ninja Cross Parkour System

⚠️ Wichtig: Ändern Sie die Standardpasswörter in der Produktionsumgebung!

Reference in New Issue View Git Blame Copy Permalink