root 6cdc437d3e Update API documentation to reflect PyP100 migration

- 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>

2025-03-12 12:22:55 +01:00

11 KiB

Raw Permalink Blame History

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 (Steckdosen) zurück.

Erfolgsantwort:

[
  {
    "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:

{
  "name": "string",
  "description": "string",
  "ipAddress": "string" // IP-Adresse der Tapo-Steckdose
}

Erfolgsantwort:

{
  "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:

{
  "id": "uuid-string",
  "name": "string",
  "description": "string",
  "status": 0, // 0 = available, 1 = busy
  "latestJob": {
    // Job-Objekt oder null, wenn kein aktiver Job
  }
}

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",
  "description": "string",
  "ipAddress": "string", // IP-Adresse der Tapo-Steckdose
  "status": 0 // 0 = available, 1 = busy
}

Erfolgsantwort:

{
  "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:

{
  "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": "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:

{
  "printerId": "uuid-string",
  "durationInMinutes": 60,
  "comments": "string"
}

Erfolgsantwort:

{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 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": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 30
}

Fehlerantwort:

{
  "message": "Nicht gefunden!"
}

Druckauftrag Kommentare aktualisieren

Endpunkt: PUT /api/jobs/{jobId}/comments

Beschreibung: Aktualisiert die Kommentare eines Druckauftrags.

Request-Body:

{
  "comments": "string"
}

Erfolgsantwort:

{
  "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:

{
  "reason": "string" // Optional
}

Erfolgsantwort:

{
  "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:

{
  "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:

{
  "minutes": 30, // Zusätzliche Minuten
  "hours": 0 // Zusätzliche Stunden (optional)
}

Erfolgsantwort:

{
  "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:

{
  "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,
  "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:

{
  "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:

{
  "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

11 KiB Raw Permalink Blame History

MYP Backend API-Dokumentation

Basis-URL

Authentifizierung

Benutzerregistrierung

Benutzeranmeldung

Initialer Administrator

Benutzer-Endpunkte

Alle Benutzer abrufen (Admin)

Benutzer abrufen (Admin)

Benutzer aktualisieren (Admin)

Benutzer löschen (Admin)

Drucker-Endpunkte

Alle Drucker abrufen

Drucker hinzufügen (Admin)

Drucker abrufen

Drucker aktualisieren (Admin)

Drucker löschen (Admin)

Druckauftrags-Endpunkte

Alle Druckaufträge abrufen

Druckauftrag erstellen

Druckauftrag abrufen

Druckauftrag Kommentare aktualisieren

Druckauftrag abbrechen

Druckauftrag vorzeitig beenden

Druckauftrag verlängern

Druckauftrag löschen

Verbleibende Zeit eines Druckauftrags abrufen

Status eines Druckauftrags abrufen

Statistik-Endpunkte

Systemstatistiken abrufen (Admin)

Test-Endpunkt

API-Test

Fehlercodes

11 KiB

Raw Permalink Blame History