diff options
Diffstat (limited to 'Documentation/rest-api.txt')
| -rw-r--r-- | Documentation/rest-api.txt | 450 |
1 files changed, 109 insertions, 341 deletions
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt index 2f9d03ff3d..303fc4b5ca 100644 --- a/Documentation/rest-api.txt +++ b/Documentation/rest-api.txt @@ -5,6 +5,17 @@ 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. +Endpoints +--------- +link:rest-api-accounts.html[/accounts/]:: + Account related REST endpoints +link:rest-api-changes.html[/changes/]:: + Change related REST endpoints +link:rest-api-groups.html[/groups/]:: + Group related REST endpoints +link:rest-api-projects.html[/projects/]:: + Project related REST endpoints + Protocol Details ---------------- @@ -21,11 +32,19 @@ 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/`. +[[preconditions]] +Preconditions +~~~~~~~~~~~~~ +Clients can request PUT to create a new resource and not overwrite +an existing one by adding `If-None-Match: *` to the request HTTP +headers. If the named resource already exists the server will respond +with HTTP 412 Precondition Failed. + [[output]] Output Format ~~~~~~~~~~~~~ -Most APIs return text format by default. JSON can be requested -by setting the `Accept` HTTP request header to include +Most APIs return pretty printed JSON by default. Compact JSON can be +requested by setting the `Accept` HTTP request header to include `application/json`, for example: ---- @@ -43,350 +62,99 @@ 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. +The default JSON format is pretty, which uses extra whitespace to make +the output more readable for a human. Producing (and parsing) the +non-pretty compact format is more efficient so tools should request it +by using the `Accept: application/json` header or `pp=0` query +parameter whenever possible. 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 - } - } - } - } - } - ] ----- - +[[timestamp]] +Timestamp +~~~~~~~~~ +Timestamps are given in UTC and have the format +"'yyyy-mm-dd hh:mm:ss.fffffffff'" where "'ffffffffff'" indicates the +nanoseconds. + +[[encoding]] +Encoding +~~~~~~~~ +All IDs that appear in the URL of a REST call (e.g. project name, group name) +must be URL encoded. + +[[response-codes]] +Response Codes +~~~~~~~~~~~~~~ +HTTP status codes are well defined and the Gerrit REST endpoints use +them as described in the HTTP spec. + +Here are examples for some HTTP status codes that show how they are +used in the context of the Gerrit REST API. + +400 Bad Request +^^^^^^^^^^^^^^^ +`400 Bad Request` is used if the request is not understood by the +server due to malformed syntax. + +E.g. `400 Bad Request` is returned if JSON input is expected but the +'Content-Type' of the request is not 'application/json' or the request +body doesn't contain valid JSON. + +`400 Bad Request` is also used if required input fields are not set or +if options are set which cannot be used together. + +403 Forbidden +^^^^^^^^^^^^^ +`403 Forbidden` is used if the operation is not allowed because the +calling user has no sufficient permissions. + +E.g. some REST endpoints require that the calling user has certain +link:access-control.html#global_capabilities[global capabilities] +assigned. + +`403 Forbidden` is also used if `self` is used as account ID and the +REST call was done without authentication. + +404 Not Found +^^^^^^^^^^^^^ +`404 Not Found` is returned if the resource that is specified by the +URL is not found or is not visible to the calling user. A resource +cannot be found if the URL contains a non-existing ID or view. + +405 Method Not Allowed +^^^^^^^^^^^^^^^^^^^^^^ +`405 Method Not Allowed` is used if the resource exists but doesn't +support the operation. + +E.g. some of the `/groups/` endpoints are only supported for Gerrit +internal groups, if they are invoked for an external group the response +is `405 Method Not Allowed`. + +409 Conflict +^^^^^^^^^^^^ +`409 Conflict` is used if the request cannot be completed because the +current state of the resource doesn't allow the operation. + +E.g. if you try to submit a change that is abandoned, this fails with +`409 Conflict` because the state of the change doesn't allow the submit +operation. + +`409 Conflict` is also used if you try to create a resource but the +name is already occupied by an existing resource. + +412 Precondition Failed +^^^^^^^^^^^^^^^^^^^^^^^ +`412 Precondition Failed` is used if a precondition from the request +header fields is not fulfilled as described in the link:#preconditions[ +Preconditions] section. + +422 Unprocessable Entity +^^^^^^^^^^^^^^^^^^^^^^^^ +`422 Unprocessable Entity` is returned if the ID of a resource that is +specified in the request body cannot be resolved. GERRIT ------ |