From a64c4b92d1139560212beb47f40f6467bab6dbc7 Mon Sep 17 00:00:00 2001
From: Edwin Kempin <edwin.kempin@sap.com>
Date: Wed, 23 Jan 2013 11:30:40 +0100
Subject: [PATCH] Add executable examples for GET requests to REST API
 documentation

Add examples for GET requests to the REST API documentation on which
the user can click to fire the requests. This allows users to
immediately try out the requests and play around with them.

Change-Id: If135a5e5dc53c07bc2d55a4ad82b65e251f76a8b
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
---
 Documentation/asciidoc.conf         | 11 +++++++++++
 Documentation/rest-api-accounts.txt | 10 ++++++++++
 Documentation/rest-api-changes.txt  | 10 ++++++++++
 Documentation/rest-api-groups.txt   | 10 ++++++++++
 Documentation/rest-api-projects.txt | 10 ++++++++++
 5 files changed, 51 insertions(+)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 9242f09a9a..2fe6213207 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -16,3 +16,14 @@ GERRIT=gerrituplink
   margin-top: 1.2em;
   margin-bottom: 0.5em;
 ">
+
+[macros]
+(?u)^(?P<name>get)::(?P<target>\S*?)$=#
+
+[get-blockmacro]
+<a id="{target}" onmousedown="javascript:
+  var i =  document.URL.lastIndexOf('/Documentation/');
+  var url = document.URL.substring(0, i) + '{target}';
+  document.getElementById('{target}').href = url;">
+    GET {target} HTTP/1.0
+</a>
diff --git a/Documentation/rest-api-accounts.txt b/Documentation/rest-api-accounts.txt
index 4b60212441..a423e85c87 100644
--- a/Documentation/rest-api-accounts.txt
+++ b/Documentation/rest-api-accounts.txt
@@ -52,6 +52,11 @@ Administrator that has authenticated with digest authentication:
   }
 ----
 
+.Get your own capabilities
+****
+get::/accounts/self/capabilities
+****
+
 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.
@@ -71,6 +76,11 @@ 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.
 
+.Check if you can create groups
+****
+get::/accounts/self/capabilities?q=createGroup
+****
+
 
 GERRIT
 ------
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index 15130abf07..5d164b2de8 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -74,6 +74,11 @@ 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 for the 25 most recent open changes of the projects that you watch
+****
+get::/changes/?q=status:open+is:watched&n=25
+****
+
 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
@@ -112,6 +117,11 @@ Query that retrieves changes for a user's dashboard:
   ]
 ----
 
+.Query the changes for your user dashboard
+****
+get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS
+****
+
 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
diff --git a/Documentation/rest-api-groups.txt b/Documentation/rest-api-groups.txt
index dce1b8e6b8..be1672a81b 100644
--- a/Documentation/rest-api-groups.txt
+++ b/Documentation/rest-api-groups.txt
@@ -68,6 +68,11 @@ and accepts the same options as query parameters.
   }
 ----
 
+.Get all groups
+****
+get::/groups/
+****
+
 [[group-members]]
 /groups/*/members/ (List Group Members)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,6 +106,11 @@ Lists the direct members of a group.
   ]
 ----
 
+.Get all members of the 'Administrators' group (normally group id = 1)
+****
+get::/groups/1/members/
+****
+
 To resolve the included groups of a group recursively and to list all
 members the parameter `recursive` can be set.
 
diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt
index 191856fa50..c259b9debe 100644
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -45,6 +45,11 @@ and accepts the same options as query parameters.
   }
 ----
 
+.Get all projects with their description
+****
+get::/projects/?d
+****
+
 [[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
@@ -112,6 +117,11 @@ List all dashboards for the `work/my-project` project:
   ]
 ----
 
+.Get all dashboards of the 'All-Projects' project
+****
+get::/projects/All-Projects/dashboards/
+****
+
 To retrieve only the default dashboard, add `default` to the URL:
 ----
   GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0