initial commitHEADmaster

1 files changed, 53 insertions, 0 deletions

diff --git a/www/json-api/api-dir.md b/www/json-api/api-dir.md
new file mode 100644
index 0000000..0e69394
--- /dev/null
+++ b/www/json-api/api-dir.md
@@ -0,0 +1,53 @@
+# JSON API: /dir
+([⬑JSON API Index](index.md))
+
+# Directory Listing
+
+**Status:** implemented 20120316
+
+**Required privileges:** "o". Was "h" prior to 20120720, but the HTML
+version of /dir changed permissions and this API was modified to match
+it.
+
+**Request:** `/json/dir`
+
+Options:
+
+-   `checkin=commit` (use "tip" for the latest). If checkin is not set
+    then all files from all versions of the tree are returned (but only
+    once per file - not with complete version info for each file in all
+    branches).\  
+    CLI: `--checkin|-ci CHECKIN`
+-   `name=subdirectory` name. To fetch the root directory, don't pass this
+    option, or use an empty value or "/".\  
+    CLI: use `--name|-n NAME` or pass it as the first argument after
+    the `dir` subcommand.
+
+**Response payload example:**
+
+```json
+{
+ "name":"/", /* dir name */
+ "uuid":"ac6366218035ed62254c8d458f30801273e5d4fc",
+ "checkin":"tip",
+ "entries":[{
+  "name": "ajax", /* file name/dir name fragment */
+  "isDir": true, /* only set for directories */
+  /* The following properties are ONLY set if
+   the 'checkin' parameter is provided.
+  */
+  "uuid": "..." /*only for files, not dirs*/,
+  "size": number,
+  "timestamp": number
+ },...]
+}
+```
+
+The checkin property is only set if the request includes it. The
+entry-specific uuid and size properties (e.g. `entries[0].uuid`) are
+only set if the checkin request property is set and they refer to the
+latest version of that file for the given checkin. The `isDir` property is
+only set on directory entries.
+
+This command does not recurse into subdirectories, though it "should be"
+simple enough to add the option to do so.