Gitblit devel
blame | history | patch | commit | commitdiff | ignore whitespace
James Moger
2011-11-09 e493cfdfa99ba780f1cd61c5575e169c8eb46845 
 docs/02_rpc.mkd


@@ -1,4 +1,4 @@


## JSON Remote Procedure Call (RPC) Interface



## Remote Management, Administration and Integration







*SINCE 0.7.0*







@@ -9,33 +9,16 @@






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



</table>



[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.  Some JSON RPC methods from the utility class `com.gitblit.utils.RpcUtils` are not currently used by the Gitblit Manager.







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



**NOTE:**  


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







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







@@ -43,7 +26,74 @@






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







<table>



<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>user<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 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>LIST_SETTINGS</td><td>-</td><td><em>-</em></td><td>-</td><td>ServerSettings (basic keys)</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>



</table>







### RPC/HTTP Response Codes



<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







@@ -68,6 +118,8 @@


      "libraries"



    ],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "102 KB"



  },



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



@@ -85,6 +137,8 @@


    "federationStrategy": "FEDERATE_THIS",



    "federationSets": [],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "4.8 MB"



  }



}



@@ -114,6 +168,8 @@


      "libraries"



    ],



    "isFederated": false,



    "skipSizeCalculation": false,



    "skipSummaryMetrics": false,



    "size": "102 KB"



}



</pre>



@@ -141,4 +197,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>