87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# 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 |
|
|
|