Split REST API documentation and have one page per top level resource
The documentation page that describes the REST API grew quite big as
more and more REST endpoints were implemented and it is expected that
the REST API documentation will grow further. Having all the REST API
documentation on a single page gets difficult to manage and the
overview gets lost for the readers.
Split the REST API documentation into multiple files so that there is
one page per top level resource that describes the REST endpoints that
are available for that resource.
Change-Id: Ibfd70b95ce3ba6c7d8f78e2db4e9ab05617dde13
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index d81033e..77e1fc2 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -55,579 +55,14 @@
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 HTTP/1.0
-
- )]}'
- {
- "queryLimit": {
- "min": 0,
- "max": 500
- }
- }
-----
-
-Administrator that has authenticated with digest authentication:
-----
- GET /a/accounts/self/capabilities 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?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/?d HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- {
- "external/bison": {
- "kind": "gerritcodereview#project",
- "id": "external%2Fbison",
- "description": "GNU parser generator"
- },
- "external/gcc": {
- "kind": "gerritcodereview#project",
- "id": "external%2Fgcc",
- },
- "external/openssl": {
- "kind": "gerritcodereview#project",
- "id": "external%2Fopenssl",
- "description": "encryption\ncrypto routines"
- },
- "test": {
- "kind": "gerritcodereview#project",
- "id": "test",
- "description": "\u003chtml\u003e is escaped"
- }
- }
-----
-
-[[suggest-projects]]
-The `/projects/` URL also accepts a prefix string in the `p` parameter.
-This limits the results to those projects that start with the specified
-prefix.
-List all projects that start with `platform/`:
-----
- GET /projects/?p=platform%2F HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- {
- "platform/drivers": {
- "kind": "gerritcodereview#project",
- "id": "platform%2Fdrivers",
- },
- "platform/tools": {
- "kind": "gerritcodereview#project",
- "id": "platform%2Ftools",
- }
- }
-----
-E.g. this feature can be used by suggestion client UI's to limit results.
-
-/projects/*/dashboards/ (List Dashboards)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-List custom dashboards for a project.
-
-The `/projects/{name}/dashboards/` URL expects the a URL encoded
-project name as part of the URL. If name contains / the correct
-encoding is to use `%2F`.
-
-List all dashboards for the `work/my-project` project:
-----
- GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- [
- {
- "kind": "gerritcodereview#dashboard",
- "id": "main:closed",
- "ref": "main",
- "path": "closed",
- "description": "Merged and abandoned changes in last 7 weeks",
- "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
- "default": true,
- "title": "Closed changes",
- "sections": [
- {
- "name": "Merged",
- "query": "status:merged age:7w"
- },
- {
- "name": "Abandoned",
- "query": "status:abandoned age:7w"
- }
- ]
- }
- ]
-----
-
-To retrieve only the default dashboard, add `default` to the URL:
-----
- GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- {
- "kind": "gerritcodereview#dashboard",
- "id": "main:closed",
- "ref": "main",
- "path": "closed",
- "default": true,
- ...
- }
-----
-
-[[groups]]
-/groups/ (List Groups)
-~~~~~~~~~~~~~~~~~~~~~~
-Lists the groups accessible by the caller. This is the same as
-using the link:cmd-ls-groups.html[ls-groups] command over SSH,
-and accepts the same options as query parameters.
-
-----
- GET /groups/ HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- {
- "Administrators": {
- "kind": "gerritcodereview#group",
- "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
- "description": "Gerrit Site Administrators",
- "group_id": 1,
- "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
- },
- "Anonymous Users": {
- "kind": "gerritcodereview#group",
- "id": "global%3AAnonymous-Users",
- "description": "Any user, signed-in or not",
- "group_id": 2,
- "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
- },
- "MyProject_Committers": {
- "kind": "gerritcodereview#group",
- "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
- "visible_to_all": true,
- "group_id": 6,
- "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7"
- },
- "Non-Interactive Users": {
- "kind": "gerritcodereview#group",
- "id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
- "description": "Users who perform batch actions on Gerrit",
- "group_id": 4,
- "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
- },
- "Project Owners": {
- "kind": "gerritcodereview#group",
- "id": "global%3AProject-Owners",
- "description": "Any owner of the project",
- "group_id": 5,
- "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
- },
- "Registered Users": {
- "kind": "gerritcodereview#group",
- "id": "global%3ARegistered-Users",
- "description": "Any signed-in user",
- "group_id": 3,
- "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
- }
- }
-----
-
-[[group-members]]
-/groups/*/members/ (List Group Members)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Lists the direct members of a group.
-
-----
- GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/ HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- [
- {
- "kind": "gerritcodereview#member",
- "full_name": "Jane Roe",
- "id": "1000097",
- "account_id": 1000097,
- "preferred_email": "jane.roe@example.com",
- "user_name": "jane"
- },
- {
- "kind": "gerritcodereview#member",
- "full_name": "John Doe",
- "id": "1000096",
- "account_id": 1000096,
- "preferred_email": "john.doe@example.com",
- "user_name": "doe"
- }
- ]
-----
-
-To resolve the included groups of a group recursively and to list all
-members the parameter `recursive` can be set.
-
-----
- GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/?recursive HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- [
- {
- "kind": "gerritcodereview#member",
- "full_name": "Jane Roe",
- "id": "1000097",
- "account_id": 1000097,
- "preferred_email": "jane.roe@example.com",
- "user_name": "jane"
- },
- {
- "kind": "gerritcodereview#member",
- "full_name": "John Doe",
- "id": "1000096",
- "account_id": 1000096,
- "preferred_email": "john.doe@example.com",
- "user_name": "doe"
- },
- {
- "kind": "gerritcodereview#member",
- "full_name": "Richard Roe",
- "id": "1000098",
- "account_id": 1000098,
- "preferred_email": "richard.roe@example.com",
- "user_name": "richard"
- }
- ]
-----
-
-[[included-groups]]
-/groups/*/groups/ (List Included Groups)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Lists the directly included groups of a group.
-
-----
- GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/ HTTP/1.0
-
- HTTP/1.1 200 OK
- Content-Disposition: attachment
- Content-Type: application/json;charset=UTF-8
-
- )]}'
- [
- {
- "kind": "gerritcodereview#group",
- "id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
- "name": "MyProject-Verifiers",
- "group_id": 38,
- "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
- }
- ]
-----
-
-[[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/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
-
- )]}'
- {
- "kind": "gerritcodereview#change",
- "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
- "project": "demo",
- "branch": "master",
- "change_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"
- },
- },
- {
- "kind": "gerritcodereview#change",
- "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501",
- "project": "demo",
- "branch": "master",
- "change_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/?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
-
- )]}'
- [
- [
- {
- "kind": "gerritcodereview#change",
- "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
- "project": "demo",
- "branch": "master",
- "change_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&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
-
- )]}'
- [
- {
- "kind": "gerritcodereview#change",
- "id": "demo~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
- "project": "gerrit",
- "branch": "master",
- "change_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
- }
- }
- }
- }
- }
- ]
-----
-
+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
------
