Gerrit Code Review - REST API

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) can authenticate with HTTP passwords by prefixing the endpoint URL with /a/. For example to authenticate to /projects/, request the URL /a/projects/. Gerrit will use HTTP basic authentication with the HTTP password from the user’s account settings page. This form of authentication bypasses the need for XSRF tokens.

An authorization cookie may be presented in the request URL inside the access_token query parameter. XSRF tokens are not required when a valid access_token is used in the URL.

Cross-site scripting may be supported if the administrator has configured site.allowOriginRegex.

Approved web applications running from an allowed origin can rely on CORS preflight to authorize requests requiring cookie based authentication, or mutations (POST, PUT, DELETE). Mutations require a valid XSRF token in the X-Gerrit-Auth request header.

Alternatively applications can use access_token in the URL (see above) to authorize requests. Mutations sent as POST with a request content type of text/plain can skip CORS preflight. Gerrit accepts additional query parameters $m to override the correct method (PUT, POST, DELETE) and $ct to specify the actual content type, such as application/json; charset=UTF-8. Example:

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.

The REST API is regularly extended (e.g. addition of new REST endpoints or new fields in existing JSON entities). Callers of the REST API must be able to deal with this (e.g. ignore unknown fields in the REST responses). Incompatible changes (e.g. removal of REST endpoints, altering/removal of existing fields in JSON entities) are avoided if possible, but can happen in rare cases. If they happen, they are announced in the release notes.

JSON responses are encoded using UTF-8 and use content type application/json.

By default most APIs return pretty-printed JSON, which uses extra whitespace to make the output more readable for humans.

Compact JSON can be requested by setting the pp=0 query parameter, or by setting the Accept HTTP request header to include application/json:

Producing (and parsing) the non-pretty compact format is more efficient, so tools should request it whenever possible.

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:

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.

Unknown JSON parameters will simply be ignored by Gerrit without causing an exception. This also applies to case-sensitive parameters, such as map keys.

Timestamps are given in UTC and have the format "'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'ffffffffff'" represents nanoseconds.

All IDs that appear in the URL of a REST call (e.g. project name, group name) must be URL encoded.

The Gerrit REST endpoints use HTTP status codes as described in the HTTP specification.

In most cases, the response body of an error response will be a plaintext, human-readable error message.

Here are examples that show how HTTP status codes are used in the context of the Gerrit REST API.

For each REST endpoint tracing can be enabled by setting the trace=<trace-id> request parameter. It is recommended to use the ID of the issue that is being investigated as trace ID.

It is also possible to omit the trace ID and get a unique trace ID generated.

Alternatively request tracing can also be enabled by setting the X-Gerrit-Trace header:

Enabling tracing results in additional logs with debug information that are written to the error_log. All logs that correspond to the traced request are associated with the trace ID. The trace ID is returned with the REST response in the X-Gerrit-Trace header.

Given the trace ID an administrator can find the corresponding logs and investigate issues more easily.

When invoking a REST endpoint it’s possible that the client sets a deadline after which the request should be aborted. To do this the X-Gerrit-Deadline header must be set on the request. Values must be specified using standard time unit abbreviations ('ms', 'sec', 'min', etc.).

Setting a deadline on the request overrides any server-side deadline that has been configured on the host.

This is only enabled when "X-Gerrit-UpdatedRef-Enabled" is set to "true" in the request header.

For each write REST request, we return X-Gerrit-UpdatedRef headers as the refs that were updated in the current request (involved in a ref transaction in the current request).

The format of those headers is PROJECT_NAME~REF_NAME\~OLD_SHA-1\~NEW_SHA-1. The project and ref names are URL-encoded, and must use %7E for '~'.

A new SHA-1 of 0000000000000000000000000000000000000000 is treated as a deleted ref. If the new SHA-1 is not 0000000000000000000000000000000000000000, the ref was either updated or created. If the old SHA-1 is 0000000000000000000000000000000000000000, the ref was created.

Part of Gerrit Code Review