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