API-Dokumentation

API-Dokumentation: KI-basierte JSON-REST API für Dateisystemoperationen

Kontext

URL-Basis: https://wsw.karlkratz.com/api/v1

Das API-Verzeichnis ist unter GET /api/v1/ verfügbar und liefert JSON. Die daraus erzeugte Tabelle ist die kanonische Quelle für HTTP-Verben, Pfade, Eingabefelder, Mutationspflicht und Prozessdokumentation.

Terminal-Aufruf

curl -sS https://wsw.karlkratz.com/api/v1/ | jq .

Ohne jq:

curl -sS https://wsw.karlkratz.com/api/v1/

Schulungsmodus (MVP):

• kein API-Key/JWT
• kein Rate-Limit
• vollständiges Transaktionsprotokoll; Dateiinhalt wird nur als Bytezahl erfasst

Die API ist damit ungeschützt und ausschließlich für eine kontrollierte Demo-/Schulungsumgebung gedacht. Sie darf nicht unverändert öffentlich exponiert werden.

Harte Änderungsregel

Jeder ändernde oder schreibende API-Aufruf benötigt eine bereits existierende task_id. Die ID muss bei Datei-POST, Datei-PATCH und Datei-DELETE im JSON-Body oder als Query-Parameter angegeben werden. Eine unbekannte oder fehlende ID wird vor der Operation abgewiesen.

Einzige Bootstrap-Ausnahme ist POST /api/v1/tasks: Damit wird der Task zuerst angelegt. task_detail ist dabei zwingend die Begründung für die geplante Änderung. Erst danach darf die zurückgegebene task_id für weitere Mutationen verwendet werden.

Maschinenlesbare Regel: GET /api/v1/ enthält mutation_policy.existing_task_id_required=true und beschreibt den Bootstrap-Endpoint.

Die Laufzeitvoraussetzungen für Schreibzugriffe sind unter /dok/prozesse/storage-runtime dokumentiert.

Basiskontrakte

Erfolgsantwort

{ "ok": true, "data": { ... } }

Fehlerantwort

{ "ok": false, "error": { "code": "PATH_FORBIDDEN", "message": "..." } }

Scope

• Nur innerhalb von PROJECT_ROOT/storage.
• Operationen:
• GET /api/v1/fs/list?path=
• GET /api/v1/fs/file?path=
• POST /api/v1/fs/file
• PATCH /api/v1/fs/file
• DELETE /api/v1/fs/file?path=
• Task-API:
• GET|POST /api/v1/tasks
• GET|PATCH /api/v1/tasks/{task_id}
• Protokoll:
• GET /api/v1/protokoll

Prozessreferenzen

• /dok/prozesse/path-sandbox
• /dok/prozesse/list-directory
• /dok/prozesse/read-file
• /dok/prozesse/write-file
• /dok/prozesse/modify-file
• /dok/prozesse/delete-file
• /dok/prozesse/tasks-api
• /dok/prozesse/protokoll-api

Datenmodelle

• ListEntry
• name:string
• type: "file" | "dir"
• size:int | null
• mtime:int (Unix timestamp)
• FileContent
• path:string
• content:string
• encoding:"utf-8"
• ModifyMode: replace | append | prepend
• TaskStatus: open | in_progress | done | blocked

DELETE /api/v1/fs/file?path=

Löscht eine vorhandene Datei innerhalb der Sandbox.

{
  "ok": true,
  "data": { "path": "test-ordner/test.txt", "deleted": true }
}

Der Pfad kann alternativ als JSON-Body { "path": "..." } gesendet werden. Das Löschen von Ordnern ist nicht vorgesehen.

Fehlercodes

• PATH_FORBIDDEN (403)
• VALIDATION_ERROR (400)
• NOT_FOUND (404)
• PAYLOAD_TOO_LARGE (413)
• IO_ERROR (500)
• INVALID_ENCODING (422, Dateiinhalt ist kein gültiger UTF-8-Text)
• UNSUPPORTED_MEDIA_TYPE (415, bei Schreibanfragen ohne application/json)
• METHOD_NOT_ALLOWED (405)
• TASK_REQUIRED (400)
• TASK_NOT_FOUND (404)

Schreibanfragen müssen ein JSON-Objekt mit allen im Endpoint beschriebenen Pflichtfeldern senden. Dateiinhalt und Rückgabe sind UTF-8-Text. Pro Schreib-/Änderungsanfrage sind maximal 256 KiB Inhalt erlaubt; beim Lesen maximal 1 MiB Dateiinhalte.