e344629771
Change-Id: I68ccd37c407e9d9184f743fdee78e59735cb0e5c Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
91 lines
2.7 KiB
Plaintext
91 lines
2.7 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]]
|
|
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/`.
|
|
|
|
[[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 pretty printed JSON by default. Compact 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 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.
|
|
|
|
[[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.
|
|
|
|
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
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|