diff options
Diffstat (limited to 'Documentation/rest-api.txt')
| -rw-r--r-- | Documentation/rest-api.txt | 45 |
1 files changed, 40 insertions, 5 deletions
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt index 7928512958..0957d32c52 100644 --- a/Documentation/rest-api.txt +++ b/Documentation/rest-api.txt @@ -32,12 +32,41 @@ 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 by prefixing the endpoint URL with -`/a/`. For example to authenticate to `/projects/`, request the URL -`/a/projects/`. +Users (and programs) can authenticate with HTTP passwords by prefixing +the endpoint URL with `/a/`. For example to authenticate to +`/projects/`, request the URL `/a/projects/`. Gerrit will use HTTP basic +authentication with the HTTP password from the user's account settings +page. This form of authentication bypasses the need for XSRF tokens. + +An authorization cookie may be presented in the request URL inside the +`access_token` query parameter. XSRF tokens are not required when a +valid `access_token` is used in the URL. + +[[cors]] +=== CORS + +Cross-site scripting may be supported if the administrator has configured +link:config-gerrit.html#site.allowOriginRegex[site.allowOriginRegex]. + +Approved web applications running from an allowed origin can rely on +CORS preflight to authorize requests requiring cookie based +authentication, or mutations (POST, PUT, DELETE). Mutations require a +valid XSRF token in the `X-Gerrit-Auth` request header. + +Alternatively applications can use `access_token` in the URL (see +above) to authorize requests. Mutations sent as POST with a request +content type of `text/plain` can skip CORS preflight. Gerrit accepts +additional query parameters `$m` to override the correct method (PUT, +POST, DELETE) and `$ct` to specify the actual content type, such as +`application/json; charset=UTF-8`. Example: -Gerrit uses HTTP basic authentication with the HTTP password from the -user's account settings page. +---- + POST /changes/42/topic?$m=PUT&$ct=application/json%3B%20charset%3DUTF-8&access_token=secret HTTP/1.1 + Content-Type: text/plain + Content-Length: 23 + + {"topic": "new-topic"} +---- [[preconditions]] === Preconditions @@ -78,6 +107,12 @@ 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. +[[input]] +=== Input Format +Unknown JSON parameters will simply be ignored by Gerrit without causing +an exception. This also applies to case-sensitive parameters, such as +map keys. + [[timestamp]] === Timestamp Timestamps are given in UTC and have the format |