Documentation/rest-api.txt

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.

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]