Document how to get/set/delete project dashboards via REST

Change-Id: I385a133b3577bff765b085eb4dd34ad4679bac07
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>

Documentation/rest-api-projects.txt

diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt
index 1775290..383a7d6 100644
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -273,7 +273,51 @@
 get::/projects/All-Projects/dashboards/
 ****
 
-To retrieve only the default dashboard, add `default` to the URL:
+[[get-dashboard]]
+GET /projects/\{project-name\}/dashboards/\{dashboard-id\} (Get Dashboard)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieves a project dashboard. The dashboard can be defined on that
+project or be inherited from a parent project.
+
+.Request
+----
+  GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0
+----
+
+As response a link:#dashboard-info[DashboardInfo] entity is returned
+that describes the dashboard.
+
+.Response
+----
+  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 the default dashboard of a project use `default` as
+dashboard-id.
 
 .Request
 ----
@@ -292,16 +336,112 @@
     "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"
+      }
+    ]
   }
 ----
 
+[[set-dashboard]]
+PUT /projects/\{project-name\}/dashboards/\{dashboard-id\} (Set Dashboard)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Updates/Creates a project dashboard.
+
+Currently only supported for the `default` dashboard.
+
+The creation/update information for the dashboard must be provided in
+the request body as a link:#dashboard-input[DashboardInput] entity.
+
+.Request
+----
+  PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
+  Content-Type: application/json;charset=UTF-8
+
+  {
+    "id": "main:closed",
+    "commit_message": "Define the default dashboard"
+  }
+----
+
+As response the new/updated dashboard is returned as a
+link:#dashboard-info[DashboardInfo] entity.
+
+.Response
+----
+  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"
+      }
+    ]
+  }
+----
+
+[[delete-dashboard]]
+DELETE /projects/\{project-name\}/dashboards/\{dashboard-id\} (Delete Dashboard)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes a project dashboard.
+
+Currently only supported for the `default` dashboard.
+
+A message to commit the deletion of the project dashboard can be
+specified in the request body inside a link:#dashboard-input[
+DashbaordInput] entity.
+
+Please note that some proxies prohibit request bodies for DELETE
+requests.
+
+.Request
+----
+  DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0
+----
+
+.Response
+----
+  HTTP/1.1 204 No Content
+----
+
 
 [[ids]]
 IDs
 ---
 
+\{dashboard-id\}
+~~~~~~~~~~~~~~~~
+The ID of a dashboard in the format '<ref>:<path>'.
+
+A special dashboard ID is `default` which represents the default
+dashboard of a project.
+
 \{project-name\}
 ~~~~~~~~~~~~~~~~
 The name of the project.
@@ -350,6 +490,21 @@
 The list of link:#dashboard-section-info[sections] in the dashboard.
 |===============================
 
+[[dashboard-input]]
+DashboardInput
+~~~~~~~~~~~~~~
+The `DashboardInput` entity contains information to create/update a
+project dashboard.
+
+[options="header",width="50%",cols="1,^2,4"]
+|=============================
+|Field Name      ||Description
+|`id`            |optional|
+ID of a dashboard to which this dashboard should link to.
+|`commit_message`|optional|
+Message that should be used to commit the change of the dashboard.
+|=============================
+
 [[dashboard-section-info]]
 DashboardSectionInfo
 ~~~~~~~~~~~~~~~~~~~~