Add notes on the HTTP's interface semantics

2025-11-22 13:13:10 +01:00
parent b2b1ed540b
commit 582893be70
1 changed files with 44 additions and 0 deletions
@@ -0,0 +1,44 @@
+The web interface allows working with the file system cluster using
+basic HTTP requests. There are many ways to interface with a file system
+using HTTP (like WebDAV), but for the firsts versions of ToastyFS I
+opted for some custom minimal semantics. Here are they.
+
+GET
+    If the path refers to a directory, the listing of its direct children
+    is returned as a newline-separated list of relative paths. Children
+    that are directories have ending slashes, while files don't:
+
+        image.jpg
+        Documents/
+        notes.txt
+
+    If the path refers to a file, its contents are returned. Note that
+    Range requests are not supported.
+
+    Returns 200 on success, 404 if the file/directory doesn't exist, else 5xx.
+
+HEAD
+    Works like GET but doesn't return the content (The Content-Length is
+    set as if the payload was being send).
+
+PUT
+    The server considers the resource being uploaded as a directory if the
+    path ends with a slash, and as a file otherwise:
+
+        photos/     directory
+        image.jpg   file
+
+    If the path refers to a directory and no file/directory exists at that
+    path, a new one is created and status 201 is returned. If a directory
+    existd already, statis 204 is returned. If a file existed already status
+    ??? (TODO) is returned. If the payload the request is not empty, the
+    operation fails with code 400.
+
+    If the path refers to a file, it creates that file with the specified
+    contents. If a file or directory already existed at that path, it is
+    overwritten unless the header "X-ToastyFS-Overwrite: no" is sent.
+    (TODO error codes)
+
+DELETE
+    Deletes the given file or directory. Returns 204 on success, 404 if
+    no file or directory existed at that path, else returns 5xx.