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