From fe7c01a8bd76dff240e74bb770212911e227ba59 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Fri, 03 Feb 2012 17:24:51 -0500
Subject: [PATCH] Return to Users page after add/edit team
---
docs/02_rpc.mkd | 130 +++++++++++++++++++++++++++++++------------
1 files changed, 93 insertions(+), 37 deletions(-)
diff --git a/docs/02_rpc.mkd b/docs/02_rpc.mkd
index 8265508..5cd0052 100644
--- a/docs/02_rpc.mkd
+++ b/docs/02_rpc.mkd
@@ -1,38 +1,105 @@
-## JSON Remote Procedure Call (RPC) Interface
+## Remote Management, Administration and Integration
*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.enableRpcManagement=false
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.
+The Gitblit JSON 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
+### Gitblit Manager
+
+[Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) is an example Java/Swing application that allows remote management (repository and user objects) and administration (server settings) of a Gitblit server.
+
+This application uses a combination of RSS feeds and the JSON RPC interface, both of which are part of the [Gitblit API](http://code.google.com/p/gitblit/downloads/detail?name=%API%) library, to present live information from a Gitblit server. Some JSON RPC methods from the utility class `com.gitblit.utils.RpcUtils` are not currently used by the Gitblit Manager.
+
+**NOTE:**
+Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config.
+
+### Eclipse/EGit "Import from Gitblit" Feature (Planning)
+
+One obvious goal of a Gitblit RPC mechanism would be to have an Eclipse/EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu. Batch cloning would be supported and 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.
+
+One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts. The EGit team would then implement the UI and the client-side enumeration code. This idea was raised as part of this [feature request for EGit](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251).
+
+Currently this project is in the planning stage.
+
+## RSS Query Interface
+
+At present, Gitblit does not yet support retrieving Git objects (commits, etc) via the JSON RPC mechanism. However, the repository/branch RSS feeds can be used to extract log/history information from a repository branch.
+
+The Gitblit API includes methods for retrieving and interpreting RSS feeds. The Gitblit Manager uses these methods to allow branch activity monitoring and repository searching.
<table>
-<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>permission</th><th colspan='2'>json</th></tr>
+<tr><th>url parameter</th><th>default</th><th>description</th></tr>
+<tr><td colspan='3'><b>standard query</b></td></tr>
+<tr><td><em>repository</em></td><td><em>required</em></td><td>repository name is part of the url (see examples below)</td></tr>
+<tr><td>h=</td><td><em>optional</em><br/>default: HEAD</td><td>starting branch, ref, or commit id</td></tr>
+<tr><td>l=</td><td><em>optional</em><br/>default: web.syndicationEntries</td><td>maximum return count</td></tr>
+<tr><td>pg=</td><td><em>optional</em><br/>default: 0</td><td>page number for paging<br/>(offset into history = pagenumber*maximum return count)</td></tr>
+<tr><td colspan='3'><b>search query</b></td></tr>
+<tr><td>s=</td><td><em>required</em></td><td>search string</td></tr>
+<tr><td>st=</td><td><em>optional</em><br/>default: COMMIT</td><td>search type</td></tr>
+</table>
+
+### Example RSS Queries
+
+ https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master
+ https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=documentation
+ https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=james&st=author&pg=2
+
+## JSON Remote Procedure Call (RPC) Interface
+
+### RPC Protocol Versions
+<table>
+<tbody>
+<tr><th>Release</th><th>Protocol Version</th></tr>
+<tr><td>Gitblit v0.7.0</td><td>1 (inferred version)</td></tr>
+<tr><td>Gitblit v0.8.0</td><td>2</td></tr>
+</tbody>
+</table>
+
+### RPC Request and Response Types
+<table>
+<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>user<br/>permission</th><th rowspan='2'>protocol<br/>version</th><th colspan='2'>json</th></tr>
<tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>
-<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>-</td><td>Map<String, RepositoryModel></td></tr>
-<tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>
-<tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>RepositoryModel</td><td>-</td></tr>
-<tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>
-<tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<UserModel></td></tr>
-<tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>
-<tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>UserModel</td><td>-</td></tr>
-<tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>-</td><td>-</td></tr>
-<tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>-</td><td>List<String></td></tr>
-<tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>List<String></td><td>-</td></tr>
-<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationModel></td></tr>
-<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationModel></td></tr>
-<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationProposal></td></tr>
-<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List<FederationSet></td></tr>
-<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerSettings (see example below)</td></tr>
-<tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>Map<String, String></td><td>-</td></tr>
-<tr><td>LIST_STATUS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerStatus (see example below)</td></tr>
+<tr><td colspan='6'><em>web.enableRpcServlet=true</em></td></tr>
+<tr><td>GET_PROTOCOL</td><td>-</td><td>-</td><td>2</td><td>-</td><td>Integer</td></tr>
+<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, RepositoryModel></td></tr>
+<tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map<String, List<String>></td></tr>
+<tr><td>LIST_SETTINGS</td><td>-</td><td><em>-</em></td><td>1</td><td>-</td><td>ServerSettings (basic keys)</td></tr>
+<tr><td colspan='6'><em>web.enableRpcManagement=true</em></td></tr>
+<tr><td>CREATE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
+<tr><td>EDIT_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>RepositoryModel</td><td>-</td></tr>
+<tr><td>DELETE_REPOSITORY</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>-</td><td>-</td></tr>
+<tr><td>LIST_USERS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<UserModel></td></tr>
+<tr><td>CREATE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
+<tr><td>EDIT_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>UserModel</td><td>-</td></tr>
+<tr><td>DELETE_USER</td><td>user name</td><td><em>admin</em></td><td>1</td><td>-</td><td>-</td></tr>
+<tr><td>LIST_TEAMS</td><td>-</td><td><em>admin</em></td><td>2</td><td>-</td><td>List<TeamModel></td></tr>
+<tr><td>CREATE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
+<tr><td>EDIT_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>TeamModel</td><td>-</td></tr>
+<tr><td>DELETE_TEAM</td><td>team name</td><td><em>admin</em></td><td>2</td><td>-</td><td>-</td></tr>
+<tr><td>LIST_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<String></td></tr>
+<tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>1</td><td>List<String></td><td>-</td></tr>
+<tr><td>LIST_REPOSITORY_TEAMS</td><td>repository name</td><td><em>admin</em></td><td>2</td><td>-</td><td>List<String></td></tr>
+<tr><td>SET_REPOSITORY_TEAMS</td><td>repository name</td><td><em>admin</em></td><td>2</td><td>List<String></td><td>-</td></tr>
+<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (management keys)</td></tr>
+<tr><td colspan='6'><em>web.enableRpcAdministration=true</em></td></tr>
+<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
+<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationModel></td></tr>
+<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationProposal></td></tr>
+<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List<FederationSet></td></tr>
+<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerSettings (all keys)</td></tr>
+<tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>1</td><td>Map<String, String></td><td>-</td></tr>
+<tr><td>LIST_STATUS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>ServerStatus (see example below)</td></tr>
</table>
### RPC/HTTP Response Codes
@@ -45,21 +112,6 @@
<tr><td>500</td><td>server error</td><td>Gitblit failed to process the request likely because the input object created a conflict</td></tr>
<tr><td>501</td><td>unknown request</td><td>Gitblit does not recognize the RPC request type</td></tr>
</table>
-
-### Gitblit Manager
-
-[Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) is an example Java/Swing application that allows remote administration of a Gitblit server.
-This application exercises many, but not all, 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.
-
-One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts. The EGit team would then implement the UI and the client-side enumeration code. This idea was raised as part of this [feature request for EGit](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251).
-
-Currently this project is in the planning stage.
### Example: LIST_REPOSITORIES
@@ -201,6 +253,9 @@
<pre>
{
"bootDate": "2011-10-22T12:13:00Z",
+ "version": "0.7.0-SNAPSHOT",
+ "releaseDate": "PENDING",
+ "isGO": true,
"systemProperties": {
"file.encoding": "Cp1252",
"java.home": "C:\\Program Files\\Java\\jdk1.6.0_26\\jre",
@@ -219,6 +274,7 @@
},
"heapAllocated": 128057344,
"heapFree": 120399168,
- "heapSize": 1899560960
+ "heapSize": 1899560960,
+ "servletContainer": "jetty/7.4.3.v20110701"
}
</pre>
\ No newline at end of file
--
Gitblit v1.9.1