FileVault API Dokumentation

Übersicht

Die FileVault API ist eine RESTful API, die den Zugriff auf das FileVault-System ermöglicht. Sie bietet Funktionen zur Verwaltung von Ordnern und Dateien, die im FileVault-System gespeichert sind. Die API ist auf der Basis von Java implementiert und nutzt den integrierten HttpServer.

Basiseinstellung

Die folgenden Beispiele gehen davon aus, dass der FileVault API-Server unter localhost:9090 läuft. Falls Sie einen anderen Host oder Port verwenden, passen Sie die Befehle entsprechend an.

Docker-Unterstützung

Die FileVault API kann jetzt auch in einem Docker-Container ausgeführt werden. Bitte beachten Sie, dass nur die API im Container funktionsfähig ist. Das Hauptprojekt wird weiterhin benötigt.

docker pull ghcr.io/GulfGulfinson/fileVault:latest
docker run -v ~/.filevault:/root/.filevault -p 9090:9090 ghcr.io/GulfGulfinson/fileVault:latest

Authentifizierung

Bevor Sie auf die meisten Endpunkte zugreifen können, müssen Sie sich bei der API authentifizieren.

Authentifizierungsprozess

Senden Sie eine POST-Anfrage an den /api/auth-Endpunkt mit Ihrem Passwort.
Bei erfolgreicher Authentifizierung erhalten Sie ein Token zurück.
Dieses Token müssen Sie in allen nachfolgenden Anfragen im Authorization-Header mitschicken.

Token-Verwaltung

Tokens werden im Speicher verwaltet und bleiben gültig, bis die Anwendung neu gestartet wird oder Sie sich ausloggen.
Sie können Ihr Token im lokalen Speicher Ihres Browsers speichern, um es zwischen Sitzungen beizubehalten.

API-Endpunkte

POST /api/auth

Authentifiziert einen Benutzer und gibt ein Token zurück.

Anforderungsformat: JSON mit Passwort
Antwortformat: JSON mit Token
Auth erforderlich: Nein

Linux-Beispiel (curl):

curl -X POST http://localhost:9090/api/auth \
  -H "Content-Type: application/json" \
  -d '{"password":"11111111"}'

Erwartete Antwort:

{"token":"d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8"}

GET /api/folders

Listet alle verfügbaren Ordner auf.

Antwortformat: JSON-Array mit Ordnern
Auth erforderlich: Ja

Linux-Beispiel (curl):

curl -X GET http://localhost:9090/api/folders \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8"

Erwartete Antwort:

[{"id":1,"name":"Persönlich","parentFolderId":0},{"id":2,"name":"Arbeit","parentFolderId":0},{"id":3,"name":"Dokumente","parentFolderId":1}]

POST /api/folders

Erstellt einen neuen Ordner.

Anforderungsformat: JSON mit Ordnername und optionalem übergeordneten Ordner
Antwortformat: JSON mit Informationen zum erstellten Ordner
Auth erforderlich: Ja

Linux-Beispiel (curl) - Ordner in Root-Ebene:

curl -X POST http://localhost:9090/api/folders \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8" \
  -H "Content-Type: application/json" \
  -d '{"name":"Neuer Ordner"}'

Linux-Beispiel (curl) - Unterordner erstellen:

curl -X POST http://localhost:9090/api/folders \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8" \
  -H "Content-Type: application/json" \
  -d '{"name":"Unterordner","parentFolderId":1}'

Erwartete Antwort:

{"id":4,"name":"Unterordner","parentFolderId":1}

PUT /api/folders

Aktualisiert einen bestehenden Ordner.

Anforderungsformat: JSON mit Ordner-ID und neuem Namen
Antwortformat: JSON mit aktualisierten Ordnerinformationen
Auth erforderlich: Ja

Linux-Beispiel (curl):

curl -X PUT http://localhost:9090/api/folders \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8" \
  -H "Content-Type: application/json" \
  -d '{"id":4,"name":"Umbenannter Ordner"}'

Erwartete Antwort:

{"id":4,"name":"Umbenannter Ordner"}

DELETE /api/folders?id={id}

Löscht einen Ordner anhand seiner ID.

Antwortformat: JSON mit Erfolgs- oder Fehlermeldung
Auth erforderlich: Ja
Einschränkung: Über die API können nur leere Ordner gelöscht werden.

Linux-Beispiel (curl):

curl -X DELETE "http://localhost:9090/api/folders?id=4" \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8"

Erwartete Antwort:

Ordner erfolgreich gelöscht.

Mögliche Fehlermeldung (bei Ordner mit Inhalt):

Ordner mit Inhalt können nicht über die API gelöscht werden. Bitte verwenden Sie die grafische Benutzeroberfläche (GUI), um Ordner mit Unterordnern oder Dateien zu löschen.

GET /api/files

Listet alle verfügbaren Dateien auf.

Antwortformat: JSON-Array mit Dateien
Auth erforderlich: Ja

Linux-Beispiel (curl):

curl -X GET http://localhost:9090/api/files \
  -H "Authorization: d123e4a4-5b6c-78d9-0e1f-2g3h4i56j7k8"

Erwartete Antwort:

[{"id":1,"name":"bericht.pdf","folderId":2},{"id":2,"name":"notizen.txt","folderId":1}]

GET /

Bietet ein einfaches Web-Interface zum Testen der API.

Antwortformat: HTML
Auth erforderlich: Nein (aber Funktionalität innerhalb des Interfaces erfordert Authentifizierung)

Linux-Beispiel (curl):

curl http://localhost:9090/

Dies gibt die HTML-Seite des Web-Interfaces zurück, die Sie in einem Browser öffnen können.

Fehlerbehandlung

Die API gibt verschiedene HTTP-Statuscodes zurück, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen:

200: Erfolgreiche Anfrage
201: Ressource erfolgreich erstellt
401: Nicht autorisiert (fehlende oder ungültige Authentifizierung)
405: Methode nicht erlaubt (falsche HTTP-Methode für den Endpunkt)

Fehlermeldungen werden im JSON-Format zurückgegeben, um weitere Informationen über den Fehler zu liefern.

Beispiele für Fehlerbehandlung

Beispiel für ungültige Authentifizierung:

curl -X POST http://localhost:9090/api/auth \
  -H "Content-Type: application/json" \
  -d '{"password":"falschespasswort"}'

Erwartete Antwort:

{"error":"Ungültiges Passwort. Zugriff verweigert."}

Beispiel für eine Anfrage ohne Token:

curl -X GET http://localhost:9090/api/folders

Erwartete Antwort:

{"error":"Unauthorized: Invalid or missing authentication token."}

Beispiel für eine Anfrage mit ungültigem Token:

curl -X GET http://localhost:9090/api/folders \
  -H "Authorization: ungültigestoken"

Erwartete Antwort:

{"error":"Unauthorized: Invalid or missing authentication token."}

Bekannte Einschränkungen

Ordner mit Inhalt: Ordner, die Unterordner oder Dateien enthalten, können nicht über die API gelöscht werden. Verwenden Sie stattdessen die grafische Benutzeroberfläche (GUI) für diese Operation.
Datei-Upload: Die aktuelle API-Version unterstützt keine vollständige Datei-Upload-Funktionalität über die API. Dateien müssen über die GUI hochgeladen werden.

Sicherheitsüberlegungen

Die API verwendet eine einfache tokenbasierte Authentifizierung.
Die Tokens werden im Speicher verwaltet und sind nicht persistent über Neustarts hinweg.
In einer Produktionsumgebung sollten zusätzliche Sicherheitsmaßnahmen wie HTTPS, Token-Zeitlimits und sichere Passwörter implementiert werden.