Gerrit Code Review comes with a REST like API available over HTTP. The API is suitable for automated tools to build upon, as well as supporting some ad-hoc scripting use cases.
Protocol Details
Authentication
By default all REST endpoints assume anonymous access and filter results to correspond to what anonymous users can read (which may be nothing at all).
Users (and programs) may authenticate using HTTP authentication by supplying the HTTP password from the user’s account settings page. Gerrit by default uses HTTP digest authentication. To authenticate, prefix the endpoint URL with /a/. For example to authenticate to /projects/ request URL /a/projects/.
Output Format
Most APIs return text format by default. JSON can be requested by setting the Accept HTTP request header to include application/json, for example:
GET /projects/ HTTP/1.0 Accept: application/json
JSON responses are encoded using UTF-8 and use content type application/json. The JSON response body starts with a magic prefix line that must be stripped before feeding the rest of the response body to a JSON parser:
)]}' [ ... valid JSON ... ]
The default JSON format is JSON_COMPACT, which skips unnecessary whitespace. This is not the easiest format for a human to read. Many examples in this documentation use format=JSON as a query parameter to obtain pretty formatting in the response. Producing (and parsing) the compact format is more efficient, so most tools should prefer the default compact format.
Responses will be gzip compressed by the server if the HTTP Accept-Encoding request header is set to gzip. This may save on network transfer time for larger responses.
Endpoints
/accounts/self/capabilities (Account Capabilities)
Returns the global capabilities (such as createProject or createGroup) that are enabled for the calling user. This can be used by UI tools to discover if administrative features are available to the caller, so they can hide (or show) relevant UI actions.
GET /accounts/self/capabilities?format=JSON HTTP/1.0
)]}'
{
"queryLimit": {
"min": 0,
"max": 500
}
}
Administrator that has authenticated with digest authentication:
GET /a/accounts/self/capabilities?format=JSON HTTP/1.0
Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...
)]}'
{
"administrateServer": true,
"queryLimit": {
"min": 0,
"max": 500
},
"createAccount": true,
"createGroup": true,
"createProject": true,
"killTask": true,
"viewCaches": true,
"flushCaches": true,
"viewConnections": true,
"viewQueue": true,
"startReplication": true
}
To filter the set of global capabilities the q parameter can be used. Filtering may decrease the response time by avoiding looking at every possible alternative for the caller.
GET /a/accounts/self/capabilities?format=JSON&q=createAccount&q=createGroup HTTP/1.0
Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...
)]}'
{
"createAccount": true,
"createGroup": true
}
Most results are boolean, and a field is only present when its value is true. queryLimit is a range and is presented as a nested JSON object with min and max members.
/projects/ (List Projects)
Lists the projects accessible by the caller. This is the same as using the ls-projects command over SSH, and accepts the same options as query parameters.
GET /projects/?format=JSON&d HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"external/bison": {
"description": "GNU parser generator"
},
"external/gcc": {},
"external/openssl": {
"description": "encryption\ncrypto routines"
},
"test": {
"description": "\u003chtml\u003e is escaped"
}
}
The /projects/ URL also accepts a prefix string as part of the URL. This limits the results to those projects that start with the specified prefix. List all projects that start with platform/:
GET /projects/platform/?format=JSON HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"platform/drivers": {},
"platform/tools": {}
}
E.g. this feature can be used by suggestion client UI’s to limit results.
/changes/ (Query Changes)
Queries changes visible to the caller. The query string must be provided by the q parameter. The n parameter can be used to limit the returned results.
Query for open changes of watched projects:
GET /changes/?format=JSON&q=status:open+is:watched&n=2 HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"project": "demo",
"branch": "master",
"id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"subject": "One change",
"status": "NEW",
"created": "2012-07-17 07:18:30.854000000",
"updated": "2012-07-17 07:19:27.766000000",
"reviewed": true,
"_sortkey": "001e7057000006dc",
"_number": 1756,
"owner": {
"name": "John Doe"
},
},
{
"project": "demo",
"branch": "master",
"id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
"subject": "Another change",
"status": "NEW",
"created": "2012-07-17 07:18:30.884000000",
"updated": "2012-07-17 07:18:30.885000000",
"_sortkey": "001e7056000006dd",
"_number": 1757,
"owner": {
"name": "John Doe"
},
"_more_changes": true
}
The change output is sorted by the last update time, most recently updated to oldest update.
If the n query parameter is supplied and additional changes exist that match the query beyond the end, the last change object has a _more_changes: true JSON field set. Callers can resume a query with the n query parameter, supplying the last change’s _sortkey field as the value. When going in the reverse direction with the p query parameter a _more_changes: true is put in the first change object if there are results before the first change returned.
Clients are allowed to specify more than one query by setting the q parameter multiple times. In this case the result is an array of arrays, one per query in the same order the queries were given in.
Query that retrieves changes for a user’s dashboard:
GET /changes/?format=JSON&q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
[
{
"project": "demo",
"branch": "master",
"id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"subject": "One change",
"status": "NEW",
"created": "2012-07-17 07:18:30.854000000",
"updated": "2012-07-17 07:19:27.766000000",
"reviewed": true,
"_sortkey": "001e7057000006dc",
"_number": 1756,
"owner": {
"name": "John Doe"
},
"labels": {
"Verified": {},
"Code-Review": {}
}
}
],
[],
[]
]
Additional fields can be obtained by adding o parameters, each option requires more database lookups and slows down the query response time to the client so they are generally disabled by default. Optional fields are:
-
LABELS: a summary of each label required for submit, and approvers that have granted (or rejected) with that label.
-
CURRENT_REVISION: describe the current revision (patch set) of the change, including the commit SHA-1 and URLs to fetch from.
-
ALL_REVISIONS: describe all revisions, not just current.
-
CURRENT_COMMIT: parse and output all header fields from the commit object, including message. Only valid when the current revision or all revisions are selected.
-
ALL_COMMITS: parse and output all header fields from the output revisions. If only CURRENT_REVISION was requested then only the current revision’s commit data will be output.
-
CURRENT_FILES: list files modified by the commit, including basic line counts inserted/deleted per file. Only valid when the current revision or all revisions are selected.
-
ALL_FILES: list files modified by the commit, including basic line counts inserted/deleted per file. If only the CURRENT_REVISION was requested the only that commit’s modified files will be output.
GET /changes/?q=97&format=JSON&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
{
"project": "gerrit",
"branch": "master",
"id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
"subject": "Use an EventBus to manage star icons",
"status": "NEW",
"created": "2012-04-25 00:52:25.580000000",
"updated": "2012-04-25 00:52:25.586000000",
"_sortkey": "001c9bf400000061",
"_number": 97,
"owner": {
"name": "Shawn Pearce"
},
"current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
"revisions": {
"184ebe53805e102605d11f6b143486d15c23a09c": {
"_number": 1,
"fetch": {
"git": {
"url": "git://localhost/gerrit",
"ref": "refs/changes/97/97/1"
},
"http": {
"url": "http://127.0.0.1:8080/gerrit",
"ref": "refs/changes/97/97/1"
}
},
"commit": {
"parents": [
{
"commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Migrate contributor agreements to All-Projects."
}
],
"author": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"committer": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"subject": "Use an EventBus to manage star icons",
"message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
},
"files": {
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
"lines_deleted": 8
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
"lines_inserted": 1
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
"lines_inserted": 11,
"lines_deleted": 19
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
"lines_inserted": 23,
"lines_deleted": 20
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
"status": "D",
"lines_deleted": 139
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
"status": "A",
"lines_inserted": 204
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
"lines_deleted": 9
}
}
}
}
}
]
Part of Gerrit Code Review