e016933846
This JSON end point can be used by a client to determine global server capabilities for the user, for example common names like "createProject" or "createGroup". The q parameter can be used to filter the set of capabilities to be smaller than the set recognized by this version of Gerrit. Filtering may decrease response time by avoiding looking at every possible alternative for the caller. Most results are boolean, and a field is only present when its value is true. queryLimit is a range and is presented as a nested JSON object with min and max members. $ curl --user $USER --digest 'http://localhost:8080/a/accounts/self/capabilities?format=JSON' )]}' { "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 } Change-Id: I4052ade1da986ee409cc0d532e872211b4301f2d
135 lines
3.6 KiB
Plaintext
135 lines
3.6 KiB
Plaintext
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
|
|
~~~~~~~~~~~~~~
|
|
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 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 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
|
|
}
|
|
----
|
|
|
|
[[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"
|
|
}
|
|
}
|
|
----
|
|
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|