opendev/gerrit
Code Issues Proposed changes
1706bf6abc
gerrit/Documentation/rest-api-changes.txt
Christian Aistleitner 55364017da Fix REST API documentation for changes' sortkey parameters 
To fetch previous changes, the upper case `P` parameter has to be used
according to QueryChanges instead of lower case `p`. Similarly, upper
case `N` instead of lower case `n` is required to fetch next changes.

Simply adding an alias to allow both cases of the letters to fetch
required changes is not possible, as lower case `n` is already an alias
for the limit parameter.

Change-Id: I2452ea25f35d20df99cb6026b00b0cdaf53bd394
2013-02-17 12:15:14 +00:00

274 lines
8.5 KiB
Plaintext
Raw Blame History

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, and
values permitted to be set 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]
View Git Blame Copy Permalink