Documentation.

diff --git a/docs/02_rpc.mkd b/docs/02_rpc.mkd
new file mode 100644 (file)
index 0000000..c3c59e6
--- /dev/null
+++ b/docs/02_rpc.mkd
@@ -0,0 +1,144 @@
+## JSON Remote Procedure Call (RPC) Interface\r
+\r
+*SINCE 0.7.0*\r
+\r
+Gitblit optionally allows a remote client to administer the Gitblit server.  This client could be a Java-based tool or perhaps a tool written in another language.\r
+\r
+    web.enableRpcServlet=true\r
+    web.enableRpcAdministration=false\r
+\r
+**https** is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication!\r
+\r
+The Gitblit RPC mechanism, like the Gitblit JGit servlet, syndication/feed servlet, etc, supports request-based authentication.  Making an *admin* request will trigger Gitblit's basic authentication mechanism.  Listing of repositories, generally, will not trigger this authentication mechanism unless *web.authenticateViewPages=true*.  That means its possible to allow anonymous enumeration of repositories that are not *view restricted* or *clone restricted*.  Of course, if credentials are provided then all private repositories that are available to the user account will be enumerated in the JSON response.\r
+\r
+### RPC Requests\r
+\r
+<table>\r
+<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>permission</th><th colspan='2'>json</th></tr>\r
+<tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>\r
+<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>-</td><td>Map String, RepositoryModel </td></tr>\r
+<tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>\r
+<tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>\r
+<tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>\r
+<tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List UserModel </td></tr>\r
+<tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>\r
+<tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>\r
+<tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>\r
+<tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>List String</td></tr>\r
+<tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>List String</td><td>-</td></tr>\r
+<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List FederationModel</td></tr>\r
+<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List FederationModel</td></tr>\r
+<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List FederationProposal </td></tr>\r
+<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List FederationSet </td></tr>\r
+</table>\r
+\r
+### RPC Client\r
+\r
+An example Java Swing [RPC Client application](http://code.google.com/p/gitblit/downloads/detail?name=rpcclient-%VERSION%.zip) is available and allows remote administration of repositories and users.  \r
+This application exercises most methods from the utility class `com.gitblit.utils.RpcUtils`.\r
+\r
+### EGit "Import from Gitblit" Feature (Planning)\r
+\r
+One obvious goal of a Gitblit RPC mechanism would be to have an EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu.  Cloning (hopefully batch) would be delegated to EGit.\r
+\r
+This particular project should not be difficult as the only external dependency for `com.gitblit.utils.RpcUtils` is [google-gson](http://google-gson.googlecode.com) which is already a dependency of the EGit/GitHub Mylyn feature.\r
+\r
+Currently this project is in the planning stage.\r
+\r
+### Example: LIST_REPOSITORIES\r
+\r
+**url**: https://localhost/rpc?req=LIST_REPOSITORIES  \r
+**response body**: Map&lt;String, RepositoryModel&gt; where the map key is the clone url of the repository\r
+<pre>\r
+{\r
+  "https://localhost/git/libraries/xmlapache.git": {\r
+    "name": "libraries/xmlapache.git",\r
+    "description": "apache xmlrpc client and server",\r
+    "owner": "admin",\r
+    "lastChange": "2010-01-28T22:12:06Z",\r
+    "hasCommits": true,\r
+    "showRemoteBranches": false,\r
+    "useTickets": false,\r
+    "useDocs": false,\r
+    "accessRestriction": "VIEW",\r
+    "isFrozen": false,\r
+    "showReadme": false,\r
+    "federationStrategy": "FEDERATE_THIS",\r
+    "federationSets": [\r
+      "libraries"\r
+    ],\r
+    "isFederated": false,\r
+    "size": "102 KB"\r
+  },\r
+  "https://localhost/git/libraries/smack.git": {\r
+    "name": "libraries/smack.git",\r
+    "description": "smack xmpp client",\r
+    "owner": "admin",\r
+    "lastChange": "2009-01-28T18:38:14Z",\r
+    "hasCommits": true,\r
+    "showRemoteBranches": false,\r
+    "useTickets": false,\r
+    "useDocs": false,\r
+    "accessRestriction": "VIEW",\r
+    "isFrozen": false,\r
+    "showReadme": false,\r
+    "federationStrategy": "FEDERATE_THIS",\r
+    "federationSets": [],\r
+    "isFederated": false,\r
+    "size": "4.8 MB"\r
+  }\r
+}\r
+</pre>\r
+\r
+### Example: EDIT_REPOSITORY (rename)\r
+\r
+The original repository name is specified in the *name* url parameter.  The new name is set within the JSON object.\r
+\r
+**url**: https://localhost/rpc?req=EDIT_REPOSITORY&name=libraries/xmlapache.git  \r
+**post body**: RepositoryModel\r
+<pre>\r
+{\r
+    "name": "libraries/xmlapache-renamed.git",\r
+    "description": "apache xmlrpc client and server",\r
+    "owner": "admin",\r
+    "lastChange": "2010-01-28T22:12:06Z",\r
+    "hasCommits": true,\r
+    "showRemoteBranches": false,\r
+    "useTickets": false,\r
+    "useDocs": false,\r
+    "accessRestriction": "VIEW",\r
+    "isFrozen": false,\r
+    "showReadme": false,\r
+    "federationStrategy": "FEDERATE_THIS",\r
+    "federationSets": [\r
+      "libraries"\r
+    ],\r
+    "isFederated": false,\r
+    "size": "102 KB"\r
+}\r
+</pre>\r
+\r
+### Example: LIST_USERS\r
+**url**: https://localhost/rpc?req=LIST_USERS  \r
+**response body**: List&lt;UserModel&gt;\r
+<pre>\r
+[\r
+  {\r
+    "username": "admin",\r
+    "password": "admin",\r
+    "canAdmin": true,\r
+    "excludeFromFederation": true,\r
+    "repositories": []\r
+  },\r
+  {\r
+    "username": "test",\r
+    "password": "test",\r
+    "canAdmin": false,\r
+    "excludeFromFederation": false,\r
+    "repositories": [\r
+      "libraries/xmlapache.git",\r
+      "libraries/smack.git"\r
+    ]\r
+  }\r
+]\r
+</pre>
\ No newline at end of file