From 6cdc437d3e213c7cf44eb34c58f610f4df7826af Mon Sep 17 00:00:00 2001 From: root Date: Wed, 12 Mar 2025 12:22:55 +0100 Subject: [PATCH] Update API documentation to reflect PyP100 migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- backend/docs/API_DOCS.md | 247 +++++++++++++++++++++++++++------------ 1 file changed, 173 insertions(+), 74 deletions(-) diff --git a/backend/docs/API_DOCS.md b/backend/docs/API_DOCS.md index 4f1b674..0e43753 100644 --- a/backend/docs/API_DOCS.md +++ b/backend/docs/API_DOCS.md @@ -222,18 +222,19 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Endpunkt:** `GET /api/printers` -**Beschreibung:** Gibt eine Liste aller Drucker zurück. +**Beschreibung:** Gibt eine Liste aller Drucker (Steckdosen) zurück. **Erfolgsantwort:** ```json [ { - "id": 1, + "id": "uuid-string", "name": "string", - "location": "string", - "type": "string", - "status": "string", - "description": "string" + "description": "string", + "status": 0, // 0 = available, 1 = busy + "latestJob": { + // Job-Objekt oder null, wenn kein aktiver Job + } } ] ``` @@ -250,21 +251,19 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook ```json { "name": "string", - "location": "string", - "type": "string", - "description": "string" + "description": "string", + "ipAddress": "string" // IP-Adresse der Tapo-Steckdose } ``` **Erfolgsantwort:** ```json { - "id": 1, + "id": "uuid-string", "name": "string", - "location": "string", - "type": "string", - "status": "available", - "description": "string" + "description": "string", + "status": 0, // 0 = available, 1 = busy + "latestJob": null } ``` @@ -277,12 +276,13 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Erfolgsantwort:** ```json { - "id": 1, + "id": "uuid-string", "name": "string", - "location": "string", - "type": "string", - "status": "string", - "description": "string" + "description": "string", + "status": 0, // 0 = available, 1 = busy + "latestJob": { + // Job-Objekt oder null, wenn kein aktiver Job + } } ``` @@ -305,22 +305,22 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook ```json { "name": "string", - "location": "string", - "type": "string", - "status": "string", - "description": "string" + "description": "string", + "ipAddress": "string", // IP-Adresse der Tapo-Steckdose + "status": 0 // 0 = available, 1 = busy } ``` **Erfolgsantwort:** ```json { - "id": 1, + "id": "uuid-string", "name": "string", - "location": "string", - "type": "string", - "status": "string", - "description": "string" + "description": "string", + "status": 0, // 0 = available, 1 = busy + "latestJob": { + // Job-Objekt oder null, wenn kein aktiver Job + } } ``` @@ -351,16 +351,15 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook ```json [ { - "id": 1, - "title": "string", - "start_time": "string (ISO 8601)", - "end_time": "string (ISO 8601)", - "duration": 60, - "status": "string", + "id": "uuid-string", + "socketId": "uuid-string", + "userId": "uuid-string", + "startAt": "string (ISO 8601)", + "durationInMinutes": 60, "comments": "string", - "user_id": 1, - "printer_id": 1, - "remaining_time": 30 + "aborted": false, + "abortReason": null, + "remainingMinutes": 30 } ] ``` @@ -374,9 +373,8 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Request-Body:** ```json { - "title": "string", - "duration": 60, - "printer_id": 1, + "printerId": "uuid-string", + "durationInMinutes": 60, "comments": "string" } ``` @@ -384,16 +382,15 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Erfolgsantwort:** ```json { - "id": 1, - "title": "string", - "start_time": "string (ISO 8601)", - "end_time": "string (ISO 8601)", - "duration": 60, - "status": "active", + "id": "uuid-string", + "socketId": "uuid-string", + "userId": "uuid-string", + "startAt": "string (ISO 8601)", + "durationInMinutes": 60, "comments": "string", - "user_id": 1, - "printer_id": 1, - "remaining_time": 60 + "aborted": false, + "abortReason": null, + "remainingMinutes": 60 } ``` @@ -413,16 +410,15 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Erfolgsantwort:** ```json { - "id": 1, - "title": "string", - "start_time": "string (ISO 8601)", - "end_time": "string (ISO 8601)", - "duration": 60, - "status": "string", + "id": "uuid-string", + "socketId": "uuid-string", + "userId": "uuid-string", + "startAt": "string (ISO 8601)", + "durationInMinutes": 60, "comments": "string", - "user_id": 1, - "printer_id": 1, - "remaining_time": 30 + "aborted": false, + "abortReason": null, + "remainingMinutes": 30 } ``` @@ -433,34 +429,109 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook } ``` -### Druckauftrag aktualisieren +### Druckauftrag Kommentare aktualisieren -**Endpunkt:** `PUT /api/jobs/{jobId}` +**Endpunkt:** `PUT /api/jobs/{jobId}/comments` -**Beschreibung:** Aktualisiert die Daten eines Druckauftrags. +**Beschreibung:** Aktualisiert die Kommentare eines Druckauftrags. **Request-Body:** ```json { - "status": "string", - "comments": "string", - "duration": 30 + "comments": "string" } ``` **Erfolgsantwort:** ```json { - "id": 1, - "title": "string", - "start_time": "string (ISO 8601)", - "end_time": "string (ISO 8601)", - "duration": 90, - "status": "string", + "id": "uuid-string", + "socketId": "uuid-string", + "userId": "uuid-string", + "startAt": "string (ISO 8601)", + "durationInMinutes": 60, "comments": "string", - "user_id": 1, - "printer_id": 1, - "remaining_time": 60 + "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 } ``` @@ -486,7 +557,35 @@ Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cook **Erfolgsantwort:** ```json { - "remaining_minutes": 30 + "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 } ```