39f2a54b52
With 5cd0577828
the REST endpoint to
list projects got extended to accept a prefix string as part of
the URL to limit the results to those projects starting with this
prefix. This feature was not documented in the REST API documentation.
Change-Id: Ie6a4b39700866eb5bfe8821d9e189297909726f0
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
278 lines
7.6 KiB
Plaintext
278 lines
7.6 KiB
Plaintext
Gerrit Code Review - REST API
|
|
=============================
|
|
|
|
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]]
|
|
/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`. link:json.html#queryLimit[`queryLimit`] is a range and is
|
|
presented as a nested JSON object with `min` and `max` members.
|
|
|
|
[[projects]]
|
|
/projects/ (List Projects)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Lists the projects accessible by the caller. This is the same as
|
|
using the link:cmd-ls-projects.html[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]]
|
|
/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"
|
|
},
|
|
"labels": {
|
|
"Verified": {},
|
|
"Code-Review": {}
|
|
}
|
|
},
|
|
{
|
|
"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"
|
|
},
|
|
"labels": {
|
|
"Verified": {},
|
|
"Code-Review": {}
|
|
},
|
|
"_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 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": {}
|
|
}
|
|
}
|
|
],
|
|
[],
|
|
[]
|
|
]
|
|
----
|
|
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|