| :linkattrs: | |
| = 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. | |
| See also: link:dev-rest-api.html[REST API Developers' Notes]. | |
| == Endpoints | |
| link:rest-api-access.html[/access/]:: | |
| Access Right related REST endpoints | |
| link:rest-api-accounts.html[/accounts/]:: | |
| Account related REST endpoints | |
| link:rest-api-changes.html[/changes/]:: | |
| Change related REST endpoints | |
| link:rest-api-config.html[/config/]:: | |
| Config related REST endpoints | |
| link:rest-api-groups.html[/groups/]:: | |
| Group related REST endpoints | |
| link:rest-api-plugins.html[/plugins/]:: | |
| Plugin related REST endpoints | |
| link:rest-api-projects.html[/projects/]:: | |
| Project related REST endpoints | |
| link:rest-api-documentation.html[/Documentation/]:: | |
| Documentation related REST endpoints | |
| == Protocol Details | |
| [[authentication]] | |
| === 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) can authenticate with authentication tokens 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 tokens 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. | |
| [[cors]] | |
| === CORS | |
| Cross-site scripting may be supported if the administrator has configured | |
| link:config-gerrit.html#site.allowOriginRegex[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: | |
| ---- | |
| POST /changes/42/topic?$m=PUT&$ct=application/json%3B%20charset%3DUTF-8&access_token=secret HTTP/1.1 | |
| Content-Type: text/plain | |
| Content-Length: 23 | |
| {"topic": "new-topic"} | |
| ---- | |
| [[preconditions]] | |
| === 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. | |
| [[backwards-compatibility]] | |
| === Backwards Compatibility | |
| 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 link:https://www.gerritcodereview.com/releases-readme.html[release | |
| notes]. | |
| [[output]] | |
| === Output Format | |
| 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`: | |
| ---- | |
| GET /projects/ HTTP/1.0 | |
| Accept: 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: | |
| ---- | |
| )]}' | |
| [ ... valid JSON ... ] | |
| ---- | |
| 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. | |
| [[input]] | |
| === Input Format | |
| Unknown JSON parameters will simply be ignored by Gerrit without causing | |
| an exception. This also applies to case-sensitive parameters, such as | |
| map keys. | |
| [[timestamp]] | |
| === Timestamp | |
| Timestamps are given in UTC and have the format | |
| "'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'fffffffff'" represents | |
| nanoseconds. | |
| [[encoding]] | |
| === Encoding | |
| All IDs that appear in the URL of a REST call (e.g. project name, group name) | |
| must be URL encoded. | |
| [[response-codes]] | |
| === Response Codes | |
| The Gerrit REST endpoints use HTTP status codes as described | |
| in the link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[ | |
| HTTP specification,role=external,window=_blank]. | |
| 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. | |
| ==== 400 Bad Request | |
| "`400 Bad Request`" is returned 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 returned if required input fields are not set or | |
| if options are set which cannot be used together. | |
| ==== 403 Forbidden | |
| "`403 Forbidden`" is returned if the operation is not allowed because the | |
| calling user does not have sufficient permissions. | |
| E.g. some REST endpoints require that the calling user has certain | |
| link:access-control.html#global_capabilities[global capabilities] | |
| assigned. | |
| "`403 Forbidden`" is also returned 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 returned 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 returned 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 returned if you try to create a resource but the | |
| name is already occupied by an existing resource. | |
| ==== 412 Precondition Failed | |
| "`412 Precondition Failed`" is returned if a precondition from the request | |
| header fields is not fulfilled, as described in the link:#preconditions[ | |
| 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. | |
| ==== 429 Too Many Requests | |
| "`429 Too Many Requests`" is returned if the request exhausted any set | |
| quota limits. Depending on the exhausted quota, the request may be retried | |
| with exponential backoff. | |
| [[tracing]] | |
| === Request Tracing | |
| 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. | |
| .Example Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?trace=issue/123&q=J | |
| ---- | |
| It is also possible to omit the trace ID and get a unique trace ID | |
| generated. | |
| .Example Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?trace&q=J | |
| ---- | |
| Alternatively request tracing can also be enabled by setting the | |
| `X-Gerrit-Trace` header: | |
| .Example Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?q=J | |
| X-Gerrit-Trace: issue/123 | |
| ---- | |
| 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. | |
| .Example Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| X-Gerrit-Trace: 1533885943749-8257c498 | |
| )]}' | |
| ... <json> ... | |
| ---- | |
| Given the trace ID an administrator can find the corresponding logs and | |
| investigate issues more easily. | |
| [[deadline]] | |
| === Setting a deadline | |
| 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.). | |
| .Example Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?q=J | |
| X-Gerrit-Deadline: 5m | |
| ---- | |
| Setting a deadline on the request overrides any | |
| link:config-gerrit.html#deadline.id[server-side deadline] that has been | |
| configured on the host. | |
| [[updated-refs]] | |
| === X-Gerrit-UpdatedRef | |
| 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. | |
| .Example Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 | |
| ---- | |
| .Example Response | |
| ---- | |
| HTTP/1.1 204 NO CONTENT | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| X-Gerrit-UpdatedRef: myProject~refs%2Fchanges%2F01%2F1%2F1~deadbeefdeadbeefdeadbeefdeadbeefdeadbeef~0000000000000000000000000000000000000000 | |
| X-Gerrit-UpdatedRef: myProject~refs%2Fchanges%2F01%2F1%2Fmeta~deadbeefdeadbeefdeadbeefdeadbeefdeadbeef~0000000000000000000000000000000000000000 | |
| )]}' | |
| ---- | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |