Add initial dashboard api design

2016-12-05 11:36:12 -06:00 · 2016-12-05 11:36:12 -06:00 · 2096033ef8
parent cea85aed7c
commit 2096033ef8
1 changed files with 139 additions and 0 deletions
--- a/docs/dashboards.md
+++ b/docs/dashboards.md
@ -0,0 +1,139 @@
+## Dashboard API
+
+### Visualization Metadata
+Currently, we don't know all features we want in the dashboard visualization.  So, we'll hand-wave over that until we are actually creating the dashboards.  We'll keep the codebase agile enough to add in visualization metadata as we need 'em.
+
+### TL; DR 
+Here are the objects we are thinking about; dashboards contain layouts which contain explorations.
+
+#### Dashboard
+```json
+{
+	"links": {
+		"self": "/chronograf/v1/dashboards/myid"
+	},
+	"id": "myid",
+	"layouts": [
+		"/chronograf/v1/layouts/a",
+		"/chronograf/v1/layouts/b"
+	],
+	"name": "This is my dashboard",
+	... visualization metadata here ...
+}
+```
+
+#### Layout
+(Notice that we added explorations in the cell object) 
+```json
+{
+	"id": "6dfb4d49-20dc-4157-9018-2b1b1cb75c2d",
+	"dashboards" :[
+		"/chronograf/v1/dashboards/myid"
+	],
+	"cells": [
+		{
+		  "visualization": "graph",
+		  "name": "Apache Bytes/Second",
+		  "exploration": "/chronograf/v1/explorations/1"
+		}
+	]
+}
+```
+
+#### Exploration
+This is the same object we currently use for explorations.
+
+```json
+{
+	"name": "my exploration",
+	"data":{}
+}
+
+```
+
+## API
+### /dashboards
+#### GET /dashboards
+
+Returns a list of dashboards
+
+```json
+{
+	"dashboards": [
+		{
+			"links": {
+				"self": "/chronograf/v1/dashboards/myid"
+			},
+			"id": "myid",
+			"layouts": [
+				"/chronograf/v1/layouts/a",
+				"/chronograf/v1/layouts/b"
+			],
+			"name": "This is my dashboard",
+		},
+		{
+			"links": {
+				"self": "/chronograf/v1/dashboards/myother"
+			},
+			"id": "myother",
+			"layouts": [
+				"/chronograf/v1/layouts/b",
+				"/chronograf/v1/layouts/c"
+			],
+			"name": "This is my other dashboard",
+		}
+	]
+}
+```
+#### GET /dashboards/myid
+
+Returns an single dashboard object
+
+```json
+{
+    "links": {
+        "self": "/chronograf/v1/dashboards/myid"
+    },
+    "id": "myid",
+    "layouts": [
+        "/chronograf/v1/layouts/a",
+        "/chronograf/v1/layouts/b"
+    ],
+    "name": "This is my dashboard",
+}
+```
+
+#### PUT /dashboards/myid
+We want complete updates to the dashboards because we don't know if we can actually incrementally update visualization metadata
+
+This endpoint will respond with the dashboard after update.
+
+#### DELETE 
+Removes a dashboard but will not remove the explorations or layouts.  This could lead to orphans.
+
+
+Should we have a page that lists all the explorations and layouts and associated dashboards?
+
+#### POST
+Creating a dashboard from an exploration would need to be a two-step process
+
+1. Create Layout containing exploration
+2. Create dashboard including Layout link
+
+Perhaps the creation of a new dashboard could create associated layouts?
+
+### Modifications to /layouts
+
+A layout would have an array of associated dashboards.  This is a many-to-many relationship with the dashboards.
+
+If one edits a layout it could edit the layout for all dashboards. If a layout belongs to multiple dashboards, we could prompt the user to decide if they want to edit one or all.
+
+We will add another filter parameter, `dashboard`, to layouts.
+
+To get the layouts associated with dashboards `mydashboard` and `myotherdashboard`:
+```http
+GET /chronograf/v1/layouts?dashboard=mydashboard&dashboard=myotherdashboard HTTP/1.1
+```
+
+
+