Clearly separate requests and responses in REST API documentation
Put the example requests and responses in the REST API documentation
into own boxes so that visually they are clearly separated.
Add a description of the response for the group creation, since it was
missing.
Change-Id: I904e8f204de35e0d1bba4918a46c4c6a82a6634f
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api-accounts.txt b/Documentation/rest-api-accounts.txt
index 2dfe4a2..1873475 100644
--- a/Documentation/rest-api-accounts.txt
+++ b/Documentation/rest-api-accounts.txt
@@ -16,8 +16,16 @@
by UI tools to discover if administrative features are available
to the caller, so they can hide (or show) relevant UI actions.
+.Request
----
GET /accounts/self/capabilities HTTP/1.0
+----
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
)]}'
{
@@ -29,9 +37,18 @@
----
Administrator that has authenticated with digest authentication:
+
+.Request
----
GET /a/accounts/self/capabilities HTTP/1.0
Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...
+----
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
)]}'
{
@@ -61,9 +78,17 @@
Filtering may decrease the response time by avoiding looking at every
possible alternative for the caller.
+.Request
----
GET /a/accounts/self/capabilities?q=createAccount&q=createGroup HTTP/1.0
Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...
+----
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
)]}'
{
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index 82f69fa..3695d6a 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -15,9 +15,14 @@
the returned results.
Query for open changes of watched projects:
+
+.Request
----
GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -80,9 +85,14 @@
****
Query that retrieves changes for a user's dashboard:
+
+.Request
----
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
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -155,9 +165,13 @@
* `DETAILED_ACCOUNTS`: include `_account_id` and `email` fields when
referencing accounts.
+.Request
----
GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
diff --git a/Documentation/rest-api-groups.txt b/Documentation/rest-api-groups.txt
index 51f23a0..c259ef6 100644
--- a/Documentation/rest-api-groups.txt
+++ b/Documentation/rest-api-groups.txt
@@ -18,9 +18,13 @@
link:#group-info[GroupInfo] entries. The entries in the map are sorted
by group name.
+.Request
----
GET /groups/ HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -86,9 +90,13 @@
The entries in the list are sorted by full name, preferred email and
id.
+.Request
----
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/ HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -122,9 +130,13 @@
To resolve the included groups of a group recursively and to list all
members the parameter `recursive` can be set.
+.Request
----
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/?recursive HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -166,9 +178,13 @@
As result a list of link:#group-info[GroupInfo] entries is returned.
The entries in the list are sorted by group name and UUID.
+.Request
----
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/ HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -193,6 +209,7 @@
In the request body additional data for the group can be provided as
link:#group-input[GroupInput].
+.Request
----
PUT /groups/MyProject-Committers HTTP/1.0
Content-Type: application/json;charset=UTF-8
@@ -204,6 +221,31 @@
}
----
+As response the link:#group-info[GroupInfo] entity is returned that
+describes the created group.
+
+.Response
+----
+ HTTP/1.1 201 Created
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ {
+ "kind": "gerritcodereview#group",
+ "id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
+ "name": "MyProject-Committers",
+ "url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
+ "options": {
+ "kind": "gerritcodereview#groupoptions",
+ "visible_to_all": true
+ },
+ "description":"contains all committers for MyProject",
+ "group_id": 551,
+ "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
+ }
+----
+
[[ids]]
IDs
diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt
index 10a714c..9432259 100644
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -18,9 +18,13 @@
link:#project-info[ProjectInfo] entries. The entries in the map are sorted
by project name.
+.Request
----
GET /projects/?d HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -59,9 +63,14 @@
This limits the results to those projects that start with the specified
prefix.
List all projects that start with `platform/`:
+
+.Request
----
GET /projects/?p=platform%2F HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -88,9 +97,14 @@
returned.
List all dashboards for the `work/my-project` project:
+
+.Request
----
GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
@@ -126,9 +140,14 @@
****
To retrieve only the default dashboard, add `default` to the URL:
+
+.Request
----
GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
+----
+.Response
+----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
