initial commitHEADmaster

1 files changed, 86 insertions, 0 deletions

diff --git a/www/json-api/api-branch.md b/www/json-api/api-branch.md
new file mode 100644
index 0000000..a2a002b
--- /dev/null
+++ b/www/json-api/api-branch.md
@@ -0,0 +1,86 @@
+# JSON API: /branch
+([⬑JSON API Index](index.md))
+
+Jump to:
+
+* [Branch List](#list)
+* [Create Branch](#create)
+
+---
+
+<a id="list"></a>
+# Branch List
+
+**Status:** implemented, at least in draft form, on 20110921.
+
+**Required privileges:** "o"
+
+**Request:** `/json/branch/list`
+
+**Response payload example:**
+
+```json
+{
+"range":"closed",
+"current":"json", /* only when there is a local opened checkout */
+"branches":[
+  "artifact_description",
+  "bch",
+  "ben-changes-report",
+  "ben-safe-make",
+  "ben-security",
+  "ben-testing",
+  …
+]
+}
+```
+
+*Potential* TODO: add "tip" property which names the most recently
+modified branch? (How to get this?)
+
+HTTP GET/`POST.payload` options:
+
+-   `range`: a string in the set ("open", "closed", "all"),
+    case-sensitive, but only the first letter is actually evaluated.
+    Default="open". Only branches with this state are returned.
+
+CLI mode options (same semantics as HTTP equivalents), must come last on
+the CLI:
+
+-   `-r|--range all|closed|open`
+-   `-a` (equivalent to `-r all`)
+-   `-c` (equivalent to `-r closed`). Only one of `-a`/`-c` may be specified,
+    and if both are specified then which one takes precedence is
+    unspecified.
+
+
+<a id="create"></a>
+# Create Branch
+
+**Status:** implemented 20111002
+
+**Required privileges:** "w"
+
+**Request:** `/json/branch/create`
+
+**Request options:**
+
+-   `name=string` (REQUIRED) Name of new branch
+-   `basis=string` (default=trunk) Name of parent branch to branch from.
+-   `bgColor=string` (default=something ugly) In `#RRGGBB` form. (FIXME:
+    change the default to use fossil's random bgcolor technique.)
+-   `private=bool` (default=false) Determines whether the branch is
+    private or not.
+
+**Response payload example:**
+
+```json
+{
+"name":"my-branch",
+"basis":"my-other-branch",
+"uuid":"de8115db4ce388ed8d0af666ae7d90e1410be4ca",
+"isPrivate":true,
+"bgColor":"#ff0000"
+}
+```
+