gerrit/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"
    },
  },
  {
    "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"
    },
    "_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&o=LABELS 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": {}
        }
      }
    ],
    [],
    []
  ]
----

Additional fields can be obtained by adding `o` parameters, each
option requires more database lookups and slows down the query
response time to the client so they are generally disabled by
default. Optional fields are:

* `LABELS`: a summary of each label required for submit, and
  approvers that have granted (or rejected) with that label.

* `CURRENT_REVISION`: describe the current revision (patch set)
  of the change, including the commit SHA-1 and URLs to fetch from.

* `ALL_REVISIONS`: describe all revisions, not just current.

* `CURRENT_COMMIT`: parse and output all header fields from the
  commit object, including message. Only valid when the current
  revision or all revisions are selected.

* `ALL_COMMITS`: parse and output all header fields from the
  output revisions. If only `CURRENT_REVISION` was requested
  then only the current revision's commit data will be output.

* `CURRENT_FILES`: list files modified by the commit, including
  basic line counts inserted/deleted per file. Only valid when
  the current revision or all revisions are selected.

* `ALL_FILES`: list files modified by the commit, including
  basic line counts inserted/deleted per file. If only the
  `CURRENT_REVISION` was requested the only that commit's
  modified files will be output.

----
  GET /changes/?q=97&format=JSON&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0

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

  )]}'
  [
    {
      "project": "gerrit",
      "branch": "master",
      "id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
      "subject": "Use an EventBus to manage star icons",
      "status": "NEW",
      "created": "2012-04-25 00:52:25.580000000",
      "updated": "2012-04-25 00:52:25.586000000",
      "_sortkey": "001c9bf400000061",
      "_number": 97,
      "owner": {
        "name": "Shawn Pearce"
      },
      "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
      "revisions": {
        "184ebe53805e102605d11f6b143486d15c23a09c": {
          "_number": 1,
          "fetch": {
            "git": {
              "url": "git://localhost/gerrit",
              "ref": "refs/changes/97/97/1"
            },
            "http": {
              "url": "http://127.0.0.1:8080/gerrit",
              "ref": "refs/changes/97/97/1"
            }
          },
          "commit": {
            "parents": [
              {
                "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
                "subject": "Migrate contributor agreements to All-Projects."
              }
            ],
            "author": {
              "name": "Shawn O. Pearce",
              "email": "sop@google.com",
              "date": "2012-04-24 18:08:08.000000000",
              "tz": -420
            },
            "committer": {
              "name": "Shawn O. Pearce",
              "email": "sop@google.com",
              "date": "2012-04-24 18:08:08.000000000",
              "tz": -420
            },
            "subject": "Use an EventBus to manage star icons",
            "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
          },
          "files": {
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
              "lines_deleted": 8
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
              "lines_inserted": 1
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
              "lines_inserted": 11,
              "lines_deleted": 19
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
              "lines_inserted": 23,
              "lines_deleted": 20
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
              "status": "D",
              "lines_deleted": 139
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
              "status": "A",
              "lines_inserted": 204
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
              "lines_deleted": 9
            }
          }
        }
      }
    }
  ]
----


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