| Gerrit Code Review - '/changes/' REST API |
| ========================================= |
| |
| This page describes the change related REST endpoints. |
| Please also take note of the general information on the |
| link:rest-api.html[REST API]. |
| |
| Endpoints |
| --------- |
| |
| [[list-changes]] |
| GET /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: |
| |
| .Request |
| ---- |
| GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_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" |
| }, |
| }, |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "project": "demo", |
| "branch": "master", |
| "change_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 for the 25 most recent open changes of the projects that you watch |
| **** |
| get::/changes/?q=status:open+is:watched&n=25 |
| **** |
| |
| Query that retrieves changes for a user's dashboard: |
| |
| .Request |
| ---- |
| GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| [ |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_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": {} |
| } |
| } |
| ], |
| [], |
| [] |
| ] |
| ---- |
| |
| .Query the changes for your user dashboard |
| **** |
| get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS |
| **** |
| |
| 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. |
| |
| * `DETAILED_LABELS`: detailed label information, including numeric |
| values of all existing approvals, recognized label values, values |
| permitted to be set by the current user, and reviewers that may be |
| removed by the current user. |
| |
| * `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. |
| |
| * `DETAILED_ACCOUNTS`: include `_account_id` and `email` fields when |
| referencing accounts. |
| |
| .Request |
| ---- |
| GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", |
| "project": "gerrit", |
| "branch": "master", |
| "change_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] |
