Support faster cross-domain XHR calls

CORS preflight for POST, PUT, DELETE makes every mutation operation
require 2 round trips with the server.  This can increase latency for
any application running on a different origin.

There is a workaround available in modern browsers: use POST with
Content-Type: text/plain.  This does not require CORS preflight, as
servers should already be using XSRF protection strategies.

Unfortunately this is incompatible with the current REST API, as many
operations require PUT or DELETE methods, and a Content-Type of
application/json.  Support the requester to select a different method
using query parameter '$m' and Content-Type with '$ct' in the URL,
mocking the request with those.

Using this style of request still requires the user session to be
valid for access.  Accept identity through the query parameters as
'access_token'.

The XSRF token isn't necessary in this type of request as only
permitted websites would be allowed to read cookie content to obtain
the GerritAccount cookie value and include it in the URL.

Change-Id: Ic7bc5ad2e57eef27b0d2e13523be78e8a2d0a65c

Documentation/rest-api.txt

diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index 8e2bff6..0957d32 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -32,12 +32,41 @@
 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.
 
-Gerrit uses HTTP basic authentication with the HTTP password from the
-user's account settings page.
+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:
+
+----
+    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