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


@@ -1,52 +1,132 @@


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







### RPC Requests







<table>



<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>permission</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>Properties</td></tr>



</table>







### Result Codes



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.







### 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 most methods from the utility class `com.gitblit.utils.RpcUtils`.



[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.







### EGit "Import from Gitblit" Feature (Planning)



**NOTE:**  


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







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.



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



<tr><td>403</td><td>forbidden</td><td>Gitblit can not process the request for the supplied credentials</td></tr>



<tr><td>405</td><td>method not allowed</td><td>Gitblit has disallowed the processing the specified request</td></tr>



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







### Example: LIST_REPOSITORIES







@@ -71,6 +151,8 @@


      "libraries"



    ],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "102 KB"



  },



  "https://localhost/git/libraries/smack.git": {



@@ -88,6 +170,8 @@


    "federationStrategy": "FEDERATE_THIS",



    "federationSets": [],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "4.8 MB"



  }



}



@@ -117,6 +201,8 @@


      "libraries"



    ],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "102 KB"



}



</pre>



@@ -144,4 +230,66 @@


    ]



  }



]



</pre>







### Example: LIST_SETTINGS



**url**: https://localhost/rpc?req=LIST_SETTINGS  


**response body**: ServerSettings



<pre>



{



  "settings": {



      "web.siteName": {



        "name": "web.siteName",



        "currentValue": "",



        "defaultValue": "",



        "description": "Gitblit Web Settings\nIf blank Gitblit is displayed.",



        "since": "0.5.0",



        "caseSensitive": false,



        "restartRequired": false,



        "spaceDelimited": false



      },



      "web.summaryCommitCount": {



        "name": "web.summaryCommitCount",



        "currentValue": "16",



        "defaultValue": "16",



        "description": "The number of commits to display on the summary page\nValue must exceed 0 else default of 16 is used",



        "since": "0.5.0",



        "caseSensitive": false,



        "restartRequired": false,



        "spaceDelimited": false



      }



  }



}



</pre>







### Example: LIST_STATUS



**url**: https://localhost/rpc?req=LIST_STATUS  


**response body**: ServerStatus



<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",



    "java.io.tmpdir": "C:\\Users\\JAMESM~1\\AppData\\Local\\Temp\\",



    "java.runtime.name": "Java(TM) SE Runtime Environment",



    "java.runtime.version": "1.6.0_26-b03",



    "java.vendor": "Sun Microsystems Inc.",



    "java.version": "1.6.0_26",



    "java.vm.info": "mixed mode",



    "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",



    "java.vm.vendor": "Sun Microsystems Inc.",



    "java.vm.version": "20.1-b02",



    "os.arch": "amd64",



    "os.name": "Windows 7",



    "os.version": "6.1"



  },



  "heapAllocated": 128057344,



  "heapFree": 120399168,



  "heapSize": 1899560960,



  "servletContainer": "jetty/7.4.3.v20110701"



}



</pre>