| 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]] |
| 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]] |
| 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]] |
| 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`. 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]] |
| Timestamp |
| ~~~~~~~~~ |
| Timestamps are given in UTC and have the format |
| "'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'ffffffffff'" indicates the |
| nanoseconds. |
| |
| [[encoding]] |
| Encoding |
| ~~~~~~~~ |
| All IDs that appear in the URL of a REST call (e.g. project name, group name) |
| must be URL encoded. |
| |
| Endpoints |
| --------- |
| link:rest-api-accounts.html[/accounts/]:: |
| Account related REST endpoints |
| link:rest-api-changes.html[/changes/]:: |
| Change related REST endpoints |
| link:rest-api-groups.html[/groups/]:: |
| Group related REST endpoints |
| link:rest-api-projects.html[/projects/]:: |
| Project related REST endpoints |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
