From 4cd2f6126c5b094ac1d170fcd59c004c165a69a4 Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 11 Oct 2011 17:39:43 -0400 Subject: [PATCH] Documentation. --- docs/02_rpc.mkd | 144 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/02_rpc.mkd diff --git a/docs/02_rpc.mkd b/docs/02_rpc.mkd new file mode 100644 index 00000000..c3c59e62 --- /dev/null +++ b/docs/02_rpc.mkd @@ -0,0 +1,144 @@ +## JSON Remote Procedure Call (RPC) Interface + +*SINCE 0.7.0* + +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. + + web.enableRpcServlet=true + web.enableRpcAdministration=false + +**https** is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication! + +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. + +### RPC Requests + + + + + + + + + + + + + + + + + + +
url parametersrequired
permission		json
req=name=post bodyresponse body
LIST_REPOSITORIES---Map String, RepositoryModel
CREATE_REPOSITORYrepository nameadminRepositoryModel-
EDIT_REPOSITORYrepository nameadminRepositoryModel-
DELETE_REPOSITORYrepository nameadmin--
LIST_USERS-admin-List UserModel
CREATE_USERuser nameadminUserModel-
EDIT_USERuser nameadminUserModel-
DELETE_USERuser nameadmin--
LIST_REPOSITORY_MEMBERSrepository nameadmin-List String
SET_REPOSITORY_MEMBERSrepository nameadminList String-
LIST_FEDERATION_REGISTRATIONS-admin-List FederationModel
LIST_FEDERATION_RESULTS-admin-List FederationModel
LIST_FEDERATION_PROPOSALS-admin-List FederationProposal
LIST_FEDERATION_SETS-admin-List FederationSet
+ +### RPC Client + +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. +This application exercises most methods from the utility class `com.gitblit.utils.RpcUtils`. + +### EGit "Import from Gitblit" Feature (Planning) + +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. + +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. + +Currently this project is in the planning stage. + +### Example: LIST_REPOSITORIES + +**url**: https://localhost/rpc?req=LIST_REPOSITORIES +**response body**: Map<String, RepositoryModel> where the map key is the clone url of the repository +
+{
+  "https://localhost/git/libraries/xmlapache.git": {
+    "name": "libraries/xmlapache.git",
+    "description": "apache xmlrpc client and server",
+    "owner": "admin",
+    "lastChange": "2010-01-28T22:12:06Z",
+    "hasCommits": true,
+    "showRemoteBranches": false,
+    "useTickets": false,
+    "useDocs": false,
+    "accessRestriction": "VIEW",
+    "isFrozen": false,
+    "showReadme": false,
+    "federationStrategy": "FEDERATE_THIS",
+    "federationSets": [
+      "libraries"
+    ],
+    "isFederated": false,
+    "size": "102 KB"
+  },
+  "https://localhost/git/libraries/smack.git": {
+    "name": "libraries/smack.git",
+    "description": "smack xmpp client",
+    "owner": "admin",
+    "lastChange": "2009-01-28T18:38:14Z",
+    "hasCommits": true,
+    "showRemoteBranches": false,
+    "useTickets": false,
+    "useDocs": false,
+    "accessRestriction": "VIEW",
+    "isFrozen": false,
+    "showReadme": false,
+    "federationStrategy": "FEDERATE_THIS",
+    "federationSets": [],
+    "isFederated": false,
+    "size": "4.8 MB"
+  }
+}
+
+ +### Example: EDIT_REPOSITORY (rename) + +The original repository name is specified in the *name* url parameter. The new name is set within the JSON object. + +**url**: https://localhost/rpc?req=EDIT_REPOSITORY&name=libraries/xmlapache.git +**post body**: RepositoryModel +
+{
+    "name": "libraries/xmlapache-renamed.git",
+    "description": "apache xmlrpc client and server",
+    "owner": "admin",
+    "lastChange": "2010-01-28T22:12:06Z",
+    "hasCommits": true,
+    "showRemoteBranches": false,
+    "useTickets": false,
+    "useDocs": false,
+    "accessRestriction": "VIEW",
+    "isFrozen": false,
+    "showReadme": false,
+    "federationStrategy": "FEDERATE_THIS",
+    "federationSets": [
+      "libraries"
+    ],
+    "isFederated": false,
+    "size": "102 KB"
+}
+
+ +### Example: LIST_USERS +**url**: https://localhost/rpc?req=LIST_USERS +**response body**: List<UserModel> +
+[
+  {
+    "username": "admin",
+    "password": "admin",
+    "canAdmin": true,
+    "excludeFromFederation": true,
+    "repositories": []
+  },
+  {
+    "username": "test",
+    "password": "test",
+    "canAdmin": false,
+    "excludeFromFederation": false,
+    "repositories": [
+      "libraries/xmlapache.git",
+      "libraries/smack.git"
+    ]
+  }
+]
+
\ No newline at end of file -- 2.39.5