aufräumen
This commit is contained in:
548
backend/docs/API_DOCS.md
Normal file
548
backend/docs/API_DOCS.md
Normal file
@@ -0,0 +1,548 @@
|
||||
# MYP Backend API-Dokumentation
|
||||
|
||||
Dieses Dokument beschreibt detailliert die API-Endpunkte des MYP (Manage Your Printer) Backend-Systems.
|
||||
|
||||
## Basis-URL
|
||||
|
||||
Die Basis-URL für alle API-Anfragen ist: `http://localhost:5000` (Entwicklungsumgebung) oder die URL, unter der die Anwendung gehostet wird.
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cookies/Sessions, die bei der Anmeldung erstellt werden. Die Session wird für 7 Tage gespeichert.
|
||||
|
||||
### Benutzerregistrierung
|
||||
|
||||
**Endpunkt:** `POST /auth/register`
|
||||
|
||||
**Beschreibung:** Registriert einen neuen Benutzer im System.
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"username": "string", // Erforderlich
|
||||
"password": "string", // Erforderlich
|
||||
"displayName": "string", // Optional (Standard: username)
|
||||
"email": "string" // Optional
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Registrierung erfolgreich!",
|
||||
"user": {
|
||||
"id": "string",
|
||||
"username": "string",
|
||||
"displayName": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Benutzername bereits vergeben!"
|
||||
}
|
||||
```
|
||||
|
||||
### Benutzeranmeldung
|
||||
|
||||
**Endpunkt:** `POST /auth/login`
|
||||
|
||||
**Beschreibung:** Meldet einen Benutzer an und erstellt eine Session.
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"username": "string", // Erforderlich
|
||||
"password": "string" // Erforderlich
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Anmeldung erfolgreich!",
|
||||
"user": {
|
||||
"id": "string",
|
||||
"username": "string",
|
||||
"displayName": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Ungültiger Benutzername oder Passwort!"
|
||||
}
|
||||
```
|
||||
|
||||
### Initialer Administrator
|
||||
|
||||
**Endpunkt:** `POST /api/create-initial-admin`
|
||||
|
||||
**Beschreibung:** Erstellt einen initialen Admin-Benutzer, falls noch keiner existiert.
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"username": "string", // Erforderlich
|
||||
"password": "string", // Erforderlich
|
||||
"displayName": "string", // Optional (Standard: username)
|
||||
"email": "string" // Optional
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Administrator wurde erfolgreich erstellt!",
|
||||
"user": {
|
||||
"id": "string",
|
||||
"username": "string",
|
||||
"displayName": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Es existiert bereits ein Administrator!"
|
||||
}
|
||||
```
|
||||
|
||||
## Benutzer-Endpunkte
|
||||
|
||||
### Alle Benutzer abrufen (Admin)
|
||||
|
||||
**Endpunkt:** `GET /api/users`
|
||||
|
||||
**Beschreibung:** Gibt eine Liste aller Benutzer zurück.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"username": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Benutzer abrufen (Admin)
|
||||
|
||||
**Endpunkt:** `GET /api/users/{userId}`
|
||||
|
||||
**Beschreibung:** Gibt die Details eines bestimmten Benutzers zurück.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"username": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Nicht gefunden!"
|
||||
}
|
||||
```
|
||||
|
||||
### Benutzer aktualisieren (Admin)
|
||||
|
||||
**Endpunkt:** `PUT /api/users/{userId}`
|
||||
|
||||
**Beschreibung:** Aktualisiert die Daten eines Benutzers.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"username": "string",
|
||||
"email": "string",
|
||||
"password": "string",
|
||||
"role": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"username": "string",
|
||||
"email": "string",
|
||||
"role": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Benutzername bereits vergeben!"
|
||||
}
|
||||
```
|
||||
|
||||
### Benutzer löschen (Admin)
|
||||
|
||||
**Endpunkt:** `DELETE /api/users/{userId}`
|
||||
|
||||
**Beschreibung:** Löscht einen Benutzer.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Benutzer gelöscht!"
|
||||
}
|
||||
```
|
||||
|
||||
## Drucker-Endpunkte
|
||||
|
||||
### Alle Drucker abrufen
|
||||
|
||||
**Endpunkt:** `GET /api/printers`
|
||||
|
||||
**Beschreibung:** Gibt eine Liste aller Drucker zurück.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"status": "string",
|
||||
"description": "string"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Drucker hinzufügen (Admin)
|
||||
|
||||
**Endpunkt:** `POST /api/printers`
|
||||
|
||||
**Beschreibung:** Fügt einen neuen Drucker hinzu.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"description": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"status": "available",
|
||||
"description": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Drucker abrufen
|
||||
|
||||
**Endpunkt:** `GET /api/printers/{printerId}`
|
||||
|
||||
**Beschreibung:** Gibt die Details eines bestimmten Druckers zurück.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"status": "string",
|
||||
"description": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Nicht gefunden!"
|
||||
}
|
||||
```
|
||||
|
||||
### Drucker aktualisieren (Admin)
|
||||
|
||||
**Endpunkt:** `PUT /api/printers/{printerId}`
|
||||
|
||||
**Beschreibung:** Aktualisiert die Daten eines Druckers.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"status": "string",
|
||||
"description": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "string",
|
||||
"location": "string",
|
||||
"type": "string",
|
||||
"status": "string",
|
||||
"description": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Drucker löschen (Admin)
|
||||
|
||||
**Endpunkt:** `DELETE /api/printers/{printerId}`
|
||||
|
||||
**Beschreibung:** Löscht einen Drucker.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Drucker gelöscht!"
|
||||
}
|
||||
```
|
||||
|
||||
## Druckauftrags-Endpunkte
|
||||
|
||||
### Alle Druckaufträge abrufen
|
||||
|
||||
**Endpunkt:** `GET /api/jobs`
|
||||
|
||||
**Beschreibung:** Gibt eine Liste aller Druckaufträge zurück (für Admins) oder der eigenen Druckaufträge (für Benutzer).
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"title": "string",
|
||||
"start_time": "string (ISO 8601)",
|
||||
"end_time": "string (ISO 8601)",
|
||||
"duration": 60,
|
||||
"status": "string",
|
||||
"comments": "string",
|
||||
"user_id": 1,
|
||||
"printer_id": 1,
|
||||
"remaining_time": 30
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Druckauftrag erstellen
|
||||
|
||||
**Endpunkt:** `POST /api/jobs`
|
||||
|
||||
**Beschreibung:** Erstellt einen neuen Druckauftrag.
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"title": "string",
|
||||
"duration": 60,
|
||||
"printer_id": 1,
|
||||
"comments": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "string",
|
||||
"start_time": "string (ISO 8601)",
|
||||
"end_time": "string (ISO 8601)",
|
||||
"duration": 60,
|
||||
"status": "active",
|
||||
"comments": "string",
|
||||
"user_id": 1,
|
||||
"printer_id": 1,
|
||||
"remaining_time": 60
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Drucker ist nicht verfügbar!"
|
||||
}
|
||||
```
|
||||
|
||||
### Druckauftrag abrufen
|
||||
|
||||
**Endpunkt:** `GET /api/jobs/{jobId}`
|
||||
|
||||
**Beschreibung:** Gibt die Details eines bestimmten Druckauftrags zurück.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "string",
|
||||
"start_time": "string (ISO 8601)",
|
||||
"end_time": "string (ISO 8601)",
|
||||
"duration": 60,
|
||||
"status": "string",
|
||||
"comments": "string",
|
||||
"user_id": 1,
|
||||
"printer_id": 1,
|
||||
"remaining_time": 30
|
||||
}
|
||||
```
|
||||
|
||||
**Fehlerantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Nicht gefunden!"
|
||||
}
|
||||
```
|
||||
|
||||
### Druckauftrag aktualisieren
|
||||
|
||||
**Endpunkt:** `PUT /api/jobs/{jobId}`
|
||||
|
||||
**Beschreibung:** Aktualisiert die Daten eines Druckauftrags.
|
||||
|
||||
**Request-Body:**
|
||||
```json
|
||||
{
|
||||
"status": "string",
|
||||
"comments": "string",
|
||||
"duration": 30
|
||||
}
|
||||
```
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "string",
|
||||
"start_time": "string (ISO 8601)",
|
||||
"end_time": "string (ISO 8601)",
|
||||
"duration": 90,
|
||||
"status": "string",
|
||||
"comments": "string",
|
||||
"user_id": 1,
|
||||
"printer_id": 1,
|
||||
"remaining_time": 60
|
||||
}
|
||||
```
|
||||
|
||||
### Druckauftrag löschen
|
||||
|
||||
**Endpunkt:** `DELETE /api/jobs/{jobId}`
|
||||
|
||||
**Beschreibung:** Löscht einen Druckauftrag.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "Druckauftrag gelöscht!"
|
||||
}
|
||||
```
|
||||
|
||||
### Verbleibende Zeit eines Druckauftrags abrufen
|
||||
|
||||
**Endpunkt:** `GET /api/job/{jobId}/remaining-time`
|
||||
|
||||
**Beschreibung:** Gibt die verbleibende Zeit eines aktiven Druckauftrags in Minuten zurück.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"remaining_minutes": 30
|
||||
}
|
||||
```
|
||||
|
||||
## Statistik-Endpunkte
|
||||
|
||||
### Systemstatistiken abrufen (Admin)
|
||||
|
||||
**Endpunkt:** `GET /api/stats`
|
||||
|
||||
**Beschreibung:** Gibt Statistiken zu Druckern, Aufträgen und Benutzern zurück.
|
||||
|
||||
**Erforderliche Rechte:** Admin
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"printers": {
|
||||
"total": 10,
|
||||
"available": 5,
|
||||
"utilization_rate": 0.5
|
||||
},
|
||||
"jobs": {
|
||||
"total": 100,
|
||||
"active": 5,
|
||||
"completed": 90,
|
||||
"avg_duration": 120
|
||||
},
|
||||
"users": {
|
||||
"total": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Test-Endpunkt
|
||||
|
||||
### API-Test
|
||||
|
||||
**Endpunkt:** `GET /api/test`
|
||||
|
||||
**Beschreibung:** Testet, ob die API funktioniert.
|
||||
|
||||
**Erfolgsantwort:**
|
||||
```json
|
||||
{
|
||||
"message": "MYP Backend API funktioniert!"
|
||||
}
|
||||
```
|
||||
|
||||
## Fehlercodes
|
||||
|
||||
| Statuscode | Beschreibung |
|
||||
|------------|-----------------------------|
|
||||
| 200 | OK - Anfrage erfolgreich |
|
||||
| 201 | Created - Ressource erstellt |
|
||||
| 400 | Bad Request - Ungültige Anfrage |
|
||||
| 401 | Unauthorized - Authentifizierung erforderlich |
|
||||
| 403 | Forbidden - Unzureichende Rechte |
|
||||
| 404 | Not Found - Ressource nicht gefunden |
|
||||
| 500 | Internal Server Error - Serverfehler |
|
||||
Reference in New Issue
Block a user