acht-damen-tuerme-problem/docs/rest-api-schnittstellen-Konzept.md

REST-API-Konzept

Dieses API-Konzept beschreibt die wichtigsten Schnittstellen der Anwendung zum Acht-Damen-und-Türme-Problem. Die API wird vom Dashboard verwendet, um Spielbretter zu prüfen, Loesungen zu berechnen und Spielstände zu speichern oder zu laden.

Allgemeine Angaben

Punkt	Beschreibung
Datenformat	JSON
Authentifizierung	Session-Cookie nach Login
Geschützte Endpunkte	Speicherstand-Funktionen benoetigen einen angemeldeten Benutzer
Brettgroesse	4 bis 13 Felder pro Seite
Standard-Brettgroesse	8 x 8
Spielmodi	queens für Damen, rooks für Türme

Solver-API

Methode	Pfad	Zweck	Parameter / Body	Authentifizierung
POST	/check	Prüft, ob eine Figur auf ein bestimmtes Feld gesetzt werden darf.	JSON: board, row, col, mode	Nein
GET	/solve	Gibt Loesungen für das Damenproblem zurück.	Query: size	Nein
GET	/solve_trace	Gibt eine Damen-Loesung Schritt für Schritt zurück.	Query: size	Nein
GET	/solve_rooks	Gibt eine gültige Turm-Loesung zurück.	Query: size	Nein
GET	/solve_rooks_trace	Gibt eine Turm-Loesung Schritt für Schritt zurück.	Query: size	Nein

Speicherstand-API

Methode	Pfad	Zweck	Parameter / Body	Authentifizierung
POST	/save	Speichert den aktuellen Spielstand des angemeldeten Benutzers.	JSON: Spielbrett, Modus, Name, Notiz, Favorit, Schritte, Zeit, geloest	Ja
GET	/save_points	Listet alle gespeicherten Spielstände des angemeldeten Benutzers auf.	Optional: mode, board_size, favorites_only, sort	Ja
GET	/load	Lädt den neusten gespeicherten Spielstand.	Keine	Ja
GET	/load/{id}	Lädt einen bestimmten gespeicherten Spielstand.	Pfadparameter: id	Ja
POST	/save_points/{id}/favorite	Schaltet den Favoritenstatus eines Speicherstandes um.	Pfadparameter: id	Ja
DELETE	/save_points/{id}	Loescht einen bestimmten Speicherstand.	Pfadparameter: id	Ja

Login- und Seitenrouten

Methode	Pfad	Zweck	Typ
GET / POST	/register	Neues Benutzerkonto erstellen.	Formularroute
GET / POST	/login	Benutzer anmelden.	Formularroute
GET / POST	/login/verify	Zwei-Faktor-Code prüfen.	Formularroute
GET / POST	/login/settings	Passwort und Zwei-Faktor-Authentifizierung verwalten.	Formularroute
POST	/logout	Benutzer abmelden.	Formularroute
GET	/	Startseite anzeigen.	Seitenroute
GET	/dashboard	Dashboard anzeigen.	Seitenroute
GET	/privacy_policy	Datenschutzerklärung anzeigen.	Seitenroute
GET	/imprint	Impressum anzeigen.	Seitenroute

Wichtige Request-Daten

Feld	Verwendung	Beschreibung
board	/check, /save	Zweidimensionale Matrix des Spielbretts. 0 bedeutet leer, 1 bedeutet Figur.
row	/check	Zeile des zu prüfenden Feldes.
col	/check	Spalte des zu prüfenden Feldes.
mode	/check, /save, /save_points	Spielmodus: queens oder rooks.
size	Solver-Endpunkte	Gewünschte Brettgroesse.
boardSize	/save	Groesse des gespeicherten Spielbretts.
saveName	/save	Name des Speicherstandes.
saveNote	/save	Optionale Notiz zum Speicherstand.
isFavorite	/save	Gibt an, ob der Speicherstand als Favorit markiert ist.
stepCount	/save	Anzahl der ausgeführten Schritte.
elapsedSeconds	/save	Vergangene Spielzeit in Sekunden.
isSolved	/save	Gibt an, ob das Spiel geloest wurde.

Wichtige Response-Daten

Feld	Verwendung	Beschreibung
valid	/check	Gibt zurück, ob der Zug erlaubt ist.
status	/save, /save_points/{id}	Statusmeldung, zum Beispiel saved oder deleted.
save_point	/save	Neu gespeicherter Spielstand.
steps	Trace-Endpunkte	Liste der einzelnen Loesungsschritte.
solved	Trace-Endpunkte	Gibt an, ob eine Loesung gefunden wurde.
error	Fehlerfälle	Fehlermeldung, zum Beispiel wenn ein Speicherstand nicht gefunden wurde.

Fehlerfälle

Situation	Beispielantwort	HTTP-Status
Speicherstand existiert nicht oder gehoert einem anderen Benutzer.	{ "error": "Save point not found" }	404
Benutzer ist nicht angemeldet und ruft geschützte Route auf.	Weiterleitung zur Login-Seite	302
Ungültige Brettgroesse wird übergeben.	Wert wird auf erlaubten Bereich begrenzt.	200