From a768783640d289ffd1af3d67fff69296d2018651 Mon Sep 17 00:00:00 2001 From: Carsten Graf Date: Thu, 14 Aug 2025 10:02:03 +0200 Subject: [PATCH] Update API markdown --- API.md | 144 ++++++++++++++++++++++++++------------------------------- 1 file changed, 65 insertions(+), 79 deletions(-) diff --git a/API.md b/API.md index cc76f8f..b89f8f9 100644 --- a/API.md +++ b/API.md @@ -1,109 +1,95 @@ -# API- und Routenbeschreibung für das AquaMaster-Projekt +# API Documentation: AquaMaster Webserver -Diese Datei beschreibt alle HTTP-Routen (API und statische Seiten) für das AquaMaster-Projekt. Sie dient als Referenz für Frontend-Entwickler. +This document describes all available API routes provided by the webserver in `webserverrouter.h`. +All API endpoints return JSON unless otherwise noted. --- -## Statische Seiten +## Static Files -| Route | Methode | Beschreibung | Antwort (Content-Type) | -|-----------------|---------|-------------------------------------|------------------------| -| `/` | GET | Hauptseite (Timer) | HTML | -| `/settings` | GET | Einstellungen-Seite | HTML | -| `/about` | GET | Info-/About-Seite | HTML | -| `/` (static) | GET | Statische Dateien (CSS, Bilder, JS) | entspr. MIME-Type | +| Route | Method | Description | Response Type | +|------------------|--------|------------------------------|--------------| +| `/` | GET | Main page | HTML | +| `/settings` | GET | Settings page | HTML | +| `/rfid` | GET | RFID page | HTML | +| `/firmware.bin` | GET | Firmware file (SPIFFS) | Binary | --- -## API-Routen +## Timer & Data -### Timer & Daten - -| Route | Methode | Beschreibung | Body/Parameter | Antwort (Content-Type) | -|-------------------|---------|-------------------------------------|------------------------|--------------------------------| -| `/api/data` | GET | Aktuelle Timerdaten und Status | – | JSON | - -**Beispiel-Response:** -```json -{ - "time1": 12.34, - "status1": "running", - "time2": 0, - "status2": "ready", - "best1": 10.12, - "best2": 9.87, - "learningMode": false, - "learningButton": "Start Bahn 1" -} -``` +| Route | Method | Description | Request Body/Params | Response Example | +|-------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/data` | GET | Get current timer and status data | – | `{...}` | +| `/api/reset-best` | POST | Reset best times | – | `{ "success": true }` | --- -### Bestzeiten +## Button Learning -| Route | Methode | Beschreibung | Body/Parameter | Antwort (Content-Type) | -|----------------------|---------|-------------------------------------|------------------------|--------------------------------| -| `/api/reset-best` | POST | Setzt Bestzeiten zurück | – | `{ "success": true }` | +| Route | Method | Description | Request Body/Params | Response Example | +|------------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/unlearn-button` | POST | Remove all button assignments | – | `{ "success": true }` | +| `/api/start-learning` | POST | Start button learning mode | – | `{ "success": true }` | +| `/api/stop-learning` | POST | Stop button learning mode | – | `{ "success": true }` | +| `/api/learn/status` | GET | Get learning mode status | – | `{ "active": true, "step": 1 }` | +| `/api/buttons/status` | GET | Get button assignment and voltage | – | `{ "lane1Start": true, "lane1StartVoltage": 3.3, ... }` | --- -### Button-Lernmodus +## Settings -| Route | Methode | Beschreibung | Body/Parameter | Antwort (Content-Type) | -|--------------------------|---------|-------------------------------------|------------------------|--------------------------------| -| `/api/start-learning` | POST | Startet Lernmodus | – | `{ "success": true }` | -| `/api/stop-learning` | POST | Beendet Lernmodus | – | `{ "success": true }` | -| `/api/learn/status` | GET | Status des Lernmodus | – | `{ "active": true, "step": 1 }`| -| `/api/unlearn-button` | POST | Löscht alle Button-Zuordnungen | – | `{ "success": true }` | -| `/api/buttons/status` | GET | Status der Button-Zuordnung | – | JSON (siehe unten) | - -**Beispiel-Response für `/api/buttons/status`:** -```json -{ - "lane1Start": true, - "lane1Stop": false, - "lane2Start": true, - "lane2Stop": false -} -``` +| Route | Method | Description | Request Body/Params | Response Example | +|----------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/set-max-time` | POST | Set max timer and display time | `maxTime`, `maxTimeDisplay` (form params, seconds) | `{ "success": true }` | +| `/api/get-settings` | GET | Get current timer settings | – | `{ "maxTime": 300, "maxTimeDisplay": 20 }` | --- -### Einstellungen +## WiFi Configuration -| Route | Methode | Beschreibung | Body/Parameter | Antwort (Content-Type) | -|------------------------|---------|-------------------------------------|------------------------|--------------------------------| -| `/api/set-max-time` | POST | Setzt max. Laufzeit & max. Anzeigezeit | `maxTime` (Sekunden, optional), `maxTimeDisplay` (Sekunden, optional) als Form-Parameter | `{ "success": true }` oder `{ "success": false }` | -| `/api/get-settings` | GET | Liefert aktuelle Einstellungen | – | `{ "maxTime": 300, "maxTimeDisplay": 20 }` | +| Route | Method | Description | Request Body/Params | Response Example | +|-------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/set-wifi` | POST | Set WiFi SSID and password | `ssid`, `password` (form params) | `{ "success": true }` | +| `/api/get-wifi` | GET | Get current WiFi SSID and password | – | `{ "ssid": "...", "password": "..." }` | --- -### Systeminfo +## Location Configuration -| Route | Methode | Beschreibung | Antwort (Content-Type) | -|-------------------|---------|-------------------------------------|--------------------------------| -| `/api/info` | GET | Systeminfos (IP, MAC, Speicher, Lizenz, verbundene Buttons) | JSON (siehe unten) | - -**Beispiel-Response:** -```json -{ - "ip": "192.168.4.1", - "channel": 1, - "mac": "AA:BB:CC:DD:EE:FF", - "freeMemory": 123456, - "connectedButtons": 3, - "valid": "Ja", - "tier": 1 -} -``` +| Route | Method | Description | Request Body/Params | Response Example | +|----------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/set-location` | POST | Set location name and ID | `id`, `name` (form params) | `{ "success": true }` | +| `/api/get-location` | GET | Get current location | – | `{ "locationid": "..." }` | --- -## Hinweise +## Button Update & Mode -- **Alle API-Routen liefern JSON zurück.** -- **POST-Requests erwarten ggf. Form-Parameter (kein JSON-Body).** -- **Statische Seiten und Assets werden direkt ausgeliefert.** -- **Kein Authentifizierungsverfahren implementiert.** +| Route | Method | Description | Request Body/Params | Response Example | +|----------------------|--------|-------------------------------------|--------------------|------------------| +| `/api/updateButtons` | GET | Trigger MQTT update for buttons | – | `{ "success": true }` | +| `/api/set-mode` | POST | Set operational mode | `mode` (form param: "individual" or "wettkampf") | `{ "success": true }` | +| `/api/get-mode` | GET | Get current operational mode | – | `{ "mode": "individual" }` | ---- \ No newline at end of file +--- + +## System Info + +| Route | Method | Description | Request Body/Params | Response Example | +|---------------|--------|-------------------------------------|--------------------|------------------| +| `/api/info` | GET | Get system info (IP, MAC, memory, license, etc.) | – | `{ "ip": "...", "ipSTA": "...", "channel": 1, "mac": "...", "freeMemory": 123456, "connectedButtons": 3, "isOnline": true, "valid": "Ja", "tier": 1 }` | + +--- + +## WebSocket + +| Route | Description | +|---------|------------------------------------| +| `/ws` | WebSocket endpoint for live updates| + +--- + +**All API endpoints return JSON unless otherwise noted. POST requests expect form parameters (not JSON body).** + +Let me know if you need details on request/response formats \ No newline at end of file