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.
See also: REST API Developers' Notes.
Endpoints
- /access/
-
Access Right related REST endpoints
- /accounts/
-
Account related REST endpoints
- /changes/
-
Change related REST endpoints
- /config/
-
Config related REST endpoints
- /groups/
-
Group related REST endpoints
- /plugins/
-
Plugin related REST endpoints
- /projects/
-
Project related REST endpoints
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/
.
Preconditions
Clients can request PUT to create a new resource and not overwrite
an existing one by adding If-None-Match: *
to the request HTTP
headers. If the named resource already exists the server will respond
with HTTP 412 Precondition Failed.
Output Format
Most APIs return pretty printed JSON by default. Compact 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
.
To prevent against Cross Site Script Inclusion (XSSI) attacks, 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 pretty, which uses extra whitespace to make
the output more readable for a human. Producing (and parsing) the
non-pretty compact format is more efficient so tools should request it
by using the Accept: application/json
header or pp=0
query
parameter whenever possible.
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.
Timestamp
Timestamps are given in UTC and have the format "yyyy-mm-dd hh:mm:ss.fffffffff" where "ffffffffff" indicates the nanoseconds.
Encoding
All IDs that appear in the URL of a REST call (e.g. project name, group name) must be URL encoded.
Response Codes
HTTP status codes are well defined and the Gerrit REST endpoints use them as described in the HTTP spec.
Here are examples for some HTTP status codes that show how they are used in the context of the Gerrit REST API.
400 Bad Request
400 Bad Request
is used if the request is not understood by the
server due to malformed syntax.
E.g. 400 Bad Request
is returned if JSON input is expected but the
Content-Type of the request is not application/json or the request
body doesn’t contain valid JSON.
400 Bad Request
is also used if required input fields are not set or
if options are set which cannot be used together.
403 Forbidden
403 Forbidden
is used if the operation is not allowed because the
calling user has no sufficient permissions.
E.g. some REST endpoints require that the calling user has certain global capabilities assigned.
403 Forbidden
is also used if self
is used as account ID and the
REST call was done without authentication.
404 Not Found
404 Not Found
is returned if the resource that is specified by the
URL is not found or is not visible to the calling user. A resource
cannot be found if the URL contains a non-existing ID or view.
405 Method Not Allowed
405 Method Not Allowed
is used if the resource exists but doesn’t
support the operation.
E.g. some of the /groups/
endpoints are only supported for Gerrit
internal groups, if they are invoked for an external group the response
is 405 Method Not Allowed
.
409 Conflict
409 Conflict
is used if the request cannot be completed because the
current state of the resource doesn’t allow the operation.
E.g. if you try to submit a change that is abandoned, this fails with
409 Conflict
because the state of the change doesn’t allow the submit
operation.
409 Conflict
is also used if you try to create a resource but the
name is already occupied by an existing resource.
412 Precondition Failed
412 Precondition Failed
is used if a precondition from the request
header fields is not fulfilled as described in the
Preconditions section.
422 Unprocessable Entity
422 Unprocessable Entity
is returned if the ID of a resource that is
specified in the request body cannot be resolved.
Part of Gerrit Code Review