Doc: Added spec for server URL formats

readme/spec/server_file_url_format.md

@@ -0,0 +1,40 @@
+# Structure of file URLs in Joplin Server
+
+To identify a file, Joplin Server supports two types of URLs:
+
+## Access by ID
+
+**Format:** `BASE_URL/files/FILE_ID`
+
+This is the simplest way and it matches how other API items are accessed by ID.
+
+For example: `https://example.com/api/files/5c7e0f3f54434ba`
+
+## Access by full path
+
+**Format:** `BASE_URL/files/SPECIAL_DIR:/path/to/file/:`
+
+This is to access a file by its full path. In this case, the path must be prefixed by `SPECIAL_DIR`, which can only be `root` at the moment. Then to differentiate the path from URL segments, it needs to be wrapped in colons `:`.
+
+For example, to access the metadata of file `/my/file.txt`
+
+`https://example.com/api/files/root:/my/file.txt:`
+
+To access its content:
+
+`https://example.com/api/files/root:/my/file.txt:/content`
+
+To access the root only (for example to list its content):
+
+`https://example.com/api/files/root:/:`
+
+Which can also be written as:
+
+`https://example.com/api/files/root`
+
+## Difference between API and web app end points
+
+The API and web app end points are consistent in the way they access files, except that in one case the URLs will start with `/api` and the other with just `/`. For example, this would access the same file:
+
+- API: `https://example.com/api/files/root:/my/file.txt:`
+- Web: `https://example.com/files/root:/my/file.txt:`