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/`.

[[output]]
Output Format
~~~~~~~~~~~~~
Most APIs return text format by default. 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 `JSON_COMPACT`, which skips unnecessary
whitespace. This is not the easiest format for a human to read. Many
examples in this documentation use `format=JSON` as a query parameter
to obtain pretty formatting in the response. Producing (and parsing)
the compact format is more efficient, so most tools should prefer the
default compact format.

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
---------

[[accounts_self_capabilities]]
/accounts/self/capabilities (Account Capabilities)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the global capabilities (such as `createProject` or
`createGroup`) that are enabled for the calling user. This can be used
by UI tools to discover if administrative features are available
to the caller, so they can hide (or show) relevant UI actions.

----
  GET /accounts/self/capabilities?format=JSON HTTP/1.0

  )]}'
  {
    "queryLimit": {
      "min": 0,
      "max": 500
    }
  }
----

Administrator that has authenticated with digest authentication:
----
  GET /a/accounts/self/capabilities?format=JSON HTTP/1.0
  Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...

  )]}'
  {
    "administrateServer": true,
    "queryLimit": {
      "min": 0,
      "max": 500
    },
    "createAccount": true,
    "createGroup": true,
    "createProject": true,
    "killTask": true,
    "viewCaches": true,
    "flushCaches": true,
    "viewConnections": true,
    "viewQueue": true,
    "startReplication": true
  }
----

To filter the set of global capabilities the `q` parameter can be used.
Filtering may decrease the response time by avoiding looking at every
possible alternative for the caller.

----
  GET /a/accounts/self/capabilities?format=JSON&q=createAccount&q=createGroup HTTP/1.0
  Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...

  )]}'
  {
    "createAccount": true,
    "createGroup": true
  }
----

Most results are boolean, and a field is only present when its value
is `true`. link:json.html#queryLimit[`queryLimit`] is a range and is
presented as a nested JSON object with `min` and `max` members.

[[projects]]
/projects/ (List Projects)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Lists the projects accessible by the caller. This is the same as
using the link:cmd-ls-projects.html[ls-projects] command over SSH,
and accepts the same options as query parameters.

----
  GET /projects/?format=JSON&d HTTP/1.0

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8
   
  )]}'
  {
    "external/bison": {
      "description": "GNU parser generator"
    },
    "external/gcc": {},
    "external/openssl": {
      "description": "encryption\ncrypto routines"
    },
    "test": {
      "description": "\u003chtml\u003e is escaped"
    }
  }
----

[[suggest-projects]]
The `/projects/` URL also accepts a prefix string as part of the URL.
This limits the results to those projects that start with the specified
prefix.
List all projects that start with `platform/`:
----
GET /projects/platform/?format=JSON HTTP/1.0
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"platform/drivers": {},
"platform/tools": {}
}
----
E.g. this feature can be used by suggestion client UI's to limit results.

[[changes]]
/changes/ (Query Changes)
~~~~~~~~~~~~~~~~~~~~~~~~~
Queries changes visible to the caller. The query string must be
provided by the `q` parameter. The `n` parameter can be used to limit
the returned results.

Query for open changes of watched projects:
----
  GET /changes/?format=JSON&q=status:open+is:watched&n=2 HTTP/1.0

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "project": "demo",
    "branch": "master",
    "id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
    "subject": "One change",
    "status": "NEW",
    "created": "2012-07-17 07:18:30.854000000",
    "updated": "2012-07-17 07:19:27.766000000",
    "reviewed": true,
    "_sortkey": "001e7057000006dc",
    "_number": 1756,
    "owner": {
      "name": "John Doe"
    },
    "labels": {
      "Verified": {},
      "Code-Review": {}
    }
  },
  {
    "project": "demo",
    "branch": "master",
    "id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
    "subject": "Another change",
    "status": "NEW",
    "created": "2012-07-17 07:18:30.884000000",
    "updated": "2012-07-17 07:18:30.885000000",
    "_sortkey": "001e7056000006dd",
    "_number": 1757,
    "owner": {
      "name": "John Doe"
    },
    "labels": {
      "Verified": {},
      "Code-Review": {}
    },
    "_more_changes": true
  }
----

The change output is sorted by the last update time, most recently
updated to oldest update.

If the `n` query parameter is supplied and additional changes exist
that match the query beyond the end, the last change object has a
`_more_changes: true` JSON field set. Callers can resume a query with
the `n` query parameter, supplying the last change's `_sortkey` field
as the value. When going in the reverse direction with the `p` query
parameter a `_more_changes: true` is put in the first change object if
there are results *before* the first change returned.

Clients are allowed to specify more than one query by setting the `q`
parameter multiple times. In this case the result is an array of
arrays, one per query in the same order the queries were given in.

Query that retrieves changes for a user's dashboard:
----
  GET /changes/?format=JSON&q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5 HTTP/1.0

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    [
      {
        "project": "demo",
        "branch": "master",
        "id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
        "subject": "One change",
        "status": "NEW",
        "created": "2012-07-17 07:18:30.854000000",
        "updated": "2012-07-17 07:19:27.766000000",
        "reviewed": true,
        "_sortkey": "001e7057000006dc",
        "_number": 1756,
        "owner": {
          "name": "John Doe"
        },
        "labels": {
          "Verified": {},
          "Code-Review": {}
        }
      }
    ],
    [],
    []
  ]
----


GERRIT
------
Part of link:index.html[Gerrit Code Review]