548 lines
9.0 KiB
Markdown
548 lines
9.0 KiB
Markdown
# 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 | |