9.0 KiB
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:
{
"username": "string", // Erforderlich
"password": "string", // Erforderlich
"displayName": "string", // Optional (Standard: username)
"email": "string" // Optional
}
Erfolgsantwort:
{
"message": "Registrierung erfolgreich!",
"user": {
"id": "string",
"username": "string",
"displayName": "string",
"email": "string",
"role": "string"
}
}
Fehlerantwort:
{
"message": "Benutzername bereits vergeben!"
}
Benutzeranmeldung
Endpunkt: POST /auth/login
Beschreibung: Meldet einen Benutzer an und erstellt eine Session.
Request-Body:
{
"username": "string", // Erforderlich
"password": "string" // Erforderlich
}
Erfolgsantwort:
{
"message": "Anmeldung erfolgreich!",
"user": {
"id": "string",
"username": "string",
"displayName": "string",
"email": "string",
"role": "string"
}
}
Fehlerantwort:
{
"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:
{
"username": "string", // Erforderlich
"password": "string", // Erforderlich
"displayName": "string", // Optional (Standard: username)
"email": "string" // Optional
}
Erfolgsantwort:
{
"message": "Administrator wurde erfolgreich erstellt!",
"user": {
"id": "string",
"username": "string",
"displayName": "string",
"email": "string",
"role": "string"
}
}
Fehlerantwort:
{
"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:
[
{
"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:
{
"id": 1,
"username": "string",
"email": "string",
"role": "string"
}
Fehlerantwort:
{
"message": "Nicht gefunden!"
}
Benutzer aktualisieren (Admin)
Endpunkt: PUT /api/users/{userId}
Beschreibung: Aktualisiert die Daten eines Benutzers.
Erforderliche Rechte: Admin
Request-Body:
{
"username": "string",
"email": "string",
"password": "string",
"role": "string"
}
Erfolgsantwort:
{
"id": 1,
"username": "string",
"email": "string",
"role": "string"
}
Fehlerantwort:
{
"message": "Benutzername bereits vergeben!"
}
Benutzer löschen (Admin)
Endpunkt: DELETE /api/users/{userId}
Beschreibung: Löscht einen Benutzer.
Erforderliche Rechte: Admin
Erfolgsantwort:
{
"message": "Benutzer gelöscht!"
}
Drucker-Endpunkte
Alle Drucker abrufen
Endpunkt: GET /api/printers
Beschreibung: Gibt eine Liste aller Drucker zurück.
Erfolgsantwort:
[
{
"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:
{
"name": "string",
"location": "string",
"type": "string",
"description": "string"
}
Erfolgsantwort:
{
"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:
{
"id": 1,
"name": "string",
"location": "string",
"type": "string",
"status": "string",
"description": "string"
}
Fehlerantwort:
{
"message": "Nicht gefunden!"
}
Drucker aktualisieren (Admin)
Endpunkt: PUT /api/printers/{printerId}
Beschreibung: Aktualisiert die Daten eines Druckers.
Erforderliche Rechte: Admin
Request-Body:
{
"name": "string",
"location": "string",
"type": "string",
"status": "string",
"description": "string"
}
Erfolgsantwort:
{
"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:
{
"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:
[
{
"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:
{
"title": "string",
"duration": 60,
"printer_id": 1,
"comments": "string"
}
Erfolgsantwort:
{
"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:
{
"message": "Drucker ist nicht verfügbar!"
}
Druckauftrag abrufen
Endpunkt: GET /api/jobs/{jobId}
Beschreibung: Gibt die Details eines bestimmten Druckauftrags zurück.
Erfolgsantwort:
{
"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:
{
"message": "Nicht gefunden!"
}
Druckauftrag aktualisieren
Endpunkt: PUT /api/jobs/{jobId}
Beschreibung: Aktualisiert die Daten eines Druckauftrags.
Request-Body:
{
"status": "string",
"comments": "string",
"duration": 30
}
Erfolgsantwort:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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 |