6cdc437d3e
- Updated printer (socket) API endpoints to use the new data structure - Updated job API endpoints to match the current implementation - Added documentation for new endpoints: job status, abort, finish, and extend - Updated field names to match the camelCase convention used in the backend 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
647 lines
11 KiB
Markdown
647 lines
11 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 (Steckdosen) zurück.
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "uuid-string",
|
|
"name": "string",
|
|
"description": "string",
|
|
"status": 0, // 0 = available, 1 = busy
|
|
"latestJob": {
|
|
// Job-Objekt oder null, wenn kein aktiver Job
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
### Drucker hinzufügen (Admin)
|
|
|
|
**Endpunkt:** `POST /api/printers`
|
|
|
|
**Beschreibung:** Fügt einen neuen Drucker hinzu.
|
|
|
|
**Erforderliche Rechte:** Admin
|
|
|
|
**Request-Body:**
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"description": "string",
|
|
"ipAddress": "string" // IP-Adresse der Tapo-Steckdose
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"name": "string",
|
|
"description": "string",
|
|
"status": 0, // 0 = available, 1 = busy
|
|
"latestJob": null
|
|
}
|
|
```
|
|
|
|
### Drucker abrufen
|
|
|
|
**Endpunkt:** `GET /api/printers/{printerId}`
|
|
|
|
**Beschreibung:** Gibt die Details eines bestimmten Druckers zurück.
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"name": "string",
|
|
"description": "string",
|
|
"status": 0, // 0 = available, 1 = busy
|
|
"latestJob": {
|
|
// Job-Objekt oder null, wenn kein aktiver Job
|
|
}
|
|
}
|
|
```
|
|
|
|
**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",
|
|
"description": "string",
|
|
"ipAddress": "string", // IP-Adresse der Tapo-Steckdose
|
|
"status": 0 // 0 = available, 1 = busy
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"name": "string",
|
|
"description": "string",
|
|
"status": 0, // 0 = available, 1 = busy
|
|
"latestJob": {
|
|
// Job-Objekt oder null, wenn kein aktiver Job
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 30
|
|
}
|
|
]
|
|
```
|
|
|
|
### Druckauftrag erstellen
|
|
|
|
**Endpunkt:** `POST /api/jobs`
|
|
|
|
**Beschreibung:** Erstellt einen neuen Druckauftrag.
|
|
|
|
**Request-Body:**
|
|
```json
|
|
{
|
|
"printerId": "uuid-string",
|
|
"durationInMinutes": 60,
|
|
"comments": "string"
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 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": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 30
|
|
}
|
|
```
|
|
|
|
**Fehlerantwort:**
|
|
```json
|
|
{
|
|
"message": "Nicht gefunden!"
|
|
}
|
|
```
|
|
|
|
### Druckauftrag Kommentare aktualisieren
|
|
|
|
**Endpunkt:** `PUT /api/jobs/{jobId}/comments`
|
|
|
|
**Beschreibung:** Aktualisiert die Kommentare eines Druckauftrags.
|
|
|
|
**Request-Body:**
|
|
```json
|
|
{
|
|
"comments": "string"
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 30
|
|
}
|
|
```
|
|
|
|
### Druckauftrag abbrechen
|
|
|
|
**Endpunkt:** `POST /api/jobs/{jobId}/abort`
|
|
|
|
**Beschreibung:** Bricht einen laufenden Druckauftrag ab.
|
|
|
|
**Request-Body:**
|
|
```json
|
|
{
|
|
"reason": "string" // Optional
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": true,
|
|
"abortReason": "string",
|
|
"remainingMinutes": 0
|
|
}
|
|
```
|
|
|
|
### Druckauftrag vorzeitig beenden
|
|
|
|
**Endpunkt:** `POST /api/jobs/{jobId}/finish`
|
|
|
|
**Beschreibung:** Beendet einen laufenden Druckauftrag vorzeitig.
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 45, // Tatsächliche Dauer bis zum Beenden
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 0
|
|
}
|
|
```
|
|
|
|
### Druckauftrag verlängern
|
|
|
|
**Endpunkt:** `POST /api/jobs/{jobId}/extend`
|
|
|
|
**Beschreibung:** Verlängert die Laufzeit eines Druckauftrags.
|
|
|
|
**Request-Body:**
|
|
```json
|
|
{
|
|
"minutes": 30, // Zusätzliche Minuten
|
|
"hours": 0 // Zusätzliche Stunden (optional)
|
|
}
|
|
```
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 90, // Aktualisierte Gesamtdauer
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 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,
|
|
"job_status": "active", // active, completed
|
|
"socket_status": "busy" // busy, available
|
|
}
|
|
```
|
|
|
|
### Status eines Druckauftrags abrufen
|
|
|
|
**Endpunkt:** `GET /api/job/{jobId}/status`
|
|
|
|
**Beschreibung:** Gibt detaillierte Statusinformationen zu einem Druckauftrag zurück.
|
|
|
|
**Erfolgsantwort:**
|
|
```json
|
|
{
|
|
"job": {
|
|
"id": "uuid-string",
|
|
"socketId": "uuid-string",
|
|
"userId": "uuid-string",
|
|
"startAt": "string (ISO 8601)",
|
|
"durationInMinutes": 60,
|
|
"comments": "string",
|
|
"aborted": false,
|
|
"abortReason": null,
|
|
"remainingMinutes": 30
|
|
},
|
|
"status": "active", // active, completed, aborted
|
|
"socketStatus": "busy", // busy, available
|
|
"remainingMinutes": 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 | |