Gitblit devel
blame | history | patch | commit | commitdiff | ignore whitespace
James Moger
2013-01-04 8bde5a04d27e32a03e3790e39943d685c40904f7 
 docs/02_rpc.mkd


@@ -1,47 +1,124 @@


## 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







<table>



<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>user<br/>permission</th><th colspan='2'>json</th></tr>



[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 class="table">



<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 class="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>



<tr><td>Gitblit v0.9.0 - v1.0.0</td><td>3</td></tr>



<tr><td>Gitblit v1.1.0</td><td>4</td></tr>



<tr><td>Gitblit v1.2.0+</td><td>5</td></tr>



</tbody>



</table>







#### Protocol Version 5







- *SET_REPOSITORY_MEMBERS* will reject all calls because this would elevate all discrete permissions to RW+  


Use *SET_REPOSITORY_MEMBER_PERMISSIONS* instead.



- *SET_REPOSITORY_TEAMS* will reject all calls because this would elevate all discrete permissions to RW+  


Use *SET_REPOSITORY_TEAM_PERMISSIONS* instead.







### RPC Request and Response Types



<table class="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 colspan='5'><em>web.enableRpcServlet=true</em></td></tr>



<tr><td>LIST_REPOSITORIES</td><td>-</td><td>-</td><td>-</td><td>Map&lt;String, RepositoryModel&gt;</td></tr>



<tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>-</td><td>Map&lt;String, List&lt;String&gt;&gt;</td></tr>



<tr><td colspan='5'><em>web.enableRpcManagement=true</em></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&lt;UserModel&gt;</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&lt;String&gt;</td></tr>



<tr><td>SET_REPOSITORY_MEMBERS</td><td>repository name</td><td><em>admin</em></td><td>List&lt;String&gt;</td><td>-</td></tr>



<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerSettings (management keys)</td></tr>



<tr><td colspan='5'><em>web.enableRpcAdministration=true</em></td></tr>



<tr><td>LIST_FEDERATION_REGISTRATIONS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List&lt;FederationModel&gt;</td></tr>



<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List&lt;FederationModel&gt;</td></tr>



<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List&lt;FederationProposal&gt;</td></tr>



<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>-</td><td>List&lt;FederationSet&gt;</td></tr>



<tr><td>LIST_SETTINGS</td><td>-</td><td><em>admin</em></td><td>-</td><td>ServerSettings (all keys)</td></tr>



<tr><td>EDIT_SETTINGS</td><td>-</td><td><em>admin</em></td><td>Map&lt;String, String&gt;</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&lt;String, RepositoryModel&gt;</td></tr>



<tr><td>LIST_BRANCHES</td><td>-</td><td>-</td><td>1</td><td>-</td><td>Map&lt;String, List&lt;String&gt;&gt;</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&lt;UserModel&gt;</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&lt;TeamModel&gt;</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&lt;String&gt;</td></tr>



<tr><td><s>SET_REPOSITORY_MEMBERS</s></td><td><s>repository name</s></td><td><em><s>admin</s></em></td><td><s>1</s></td><td><s>List&lt;String&gt;</s></td><td>-</td></tr>



<tr><td>LIST_REPOSITORY_MEMBER_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>-</td><td>List&lt;String&gt;</td></tr>



<tr><td>SET_REPOSITORY_MEMBER_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>List&lt;String&gt;</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&lt;String&gt;</td></tr>



<tr><td><s>SET_REPOSITORY_TEAMS</s></td><td><s>repository name</s></td><td><em><s>admin</s></em></td><td><s>2</s></td><td><s>List&lt;String&gt;</s></td><td>-</td></tr>



<tr><td>LIST_REPOSITORY_TEAM_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>-</td><td>List&lt;String&gt;</td></tr>



<tr><td>SET_REPOSITORY_TEAM_PERMISSIONS</td><td>repository name</td><td><em>admin</em></td><td>5</td><td>List&lt;String&gt;</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>CLEAR_REPOSITORY_CACHE</td><td>-</td><td><em>-</em></td><td>4</td><td>-</td><td>-</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&lt;FederationModel&gt;</td></tr>



<tr><td>LIST_FEDERATION_RESULTS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationModel&gt;</td></tr>



<tr><td>LIST_FEDERATION_PROPOSALS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationProposal&gt;</td></tr>



<tr><td>LIST_FEDERATION_SETS</td><td>-</td><td><em>admin</em></td><td>1</td><td>-</td><td>List&lt;FederationSet&gt;</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&lt;String, String&gt;</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



<table>



<table class="table">



<tr><th>code</th><th>name</th><th>description</th></tr>



<tr><td>200</td><td>success</td><td>Gitblit processed the request successfully</td></tr>



<tr><td>401</td><td>unauthorized</td><td>Gitblit requires user credentials to process the request</td></tr>



@@ -50,24 +127,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`.







**NOTE:**  


Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config.







### 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