docs: update http api for api index, dashboard, folder and dashboard search

docs/sources/http_api/dashboard.md

@@ -11,6 +11,17 @@ parent = "http_api"
 
 # Dashboard API
 
+## Identifier (id) vs unique identifier (uid)
+
+The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
+
+The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
+It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URL's for accessing
+dashboards and when syncing dashboards between multiple Grafana installs, see [dashboard provisioning](/administration/provisioning/#dashboards)
+for more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
+
+The uid can have a maximum length of 40 characters.
+
 ## Create / Update dashboard
 
 `POST /api/dashboards/db`
@@ -28,6 +39,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 {
   "dashboard": {
     "id": null,
+    "uid": null,
     "title": "Production Overview",
     "tags": [ "templated" ],
     "timezone": "browser",
@@ -38,14 +50,18 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
     "schemaVersion": 6,
     "version": 0
   },
+  "folderId": 0,
   "overwrite": false
 }
 ```
 
 JSON Body schema:
 
-- **dashboard** – The complete dashboard model, id = null to create a new dashboard
+- **dashboard** – The complete dashboard model, id = null to create a new dashboard.
-- **overwrite** – Set to true if you want to overwrite existing dashboard with newer version or with same dashboard title.
+- **dashboard.id** – id = null to create a new dashboard.
+- **dashboard.uid** – Optional [unique identifier](/http_api/dashboard/#identifier-id-vs-unique-identifier-uid) when creating a dashboard. uid = null will generate a new uid.
+- **folderId** – The id of the folder to save the dashboard in.
+- **overwrite** – Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
 - **message** - Set a commit message for the version history.
 
 **Example Response**:
@@ -56,9 +72,12 @@ Content-Type: application/json; charset=UTF-8
 Content-Length: 78
 
 {
-  "slug": "production-overview",
+  "id":      1,
-  "status": "success",
+  "uid":     "cIBgcSjkk",
-  "version": 1
+  "url":     "/d/cIBgcSjkk/production-overview",
+  "status":  "success",
+  "version": 1,
+  "slug":    "production-overview" //deprecated in Grafana v5.0
 }
 ```
 
@@ -67,10 +86,18 @@ Status Codes:
 - **200** – Created
 - **400** – Errors (invalid json, missing or invalid fields, etc)
 - **401** – Unauthorized
+- **403** – Access denied
 - **412** – Precondition failed
 
-The **412** status code is used when a newer dashboard already exists (newer, its version is greater than the version that was sent). The
+The **412** status code is used for explaing that you cannot create the dashboard and why.
-same status code is also used if another dashboard exists with the same title. The response body will look like this:
+There can be different reasons for this:
+
+- The dashboard has been changed by someone else, `status=version-mismatch`
+- A dashboard with the same name in the folder already exists, `status=name-exists`
+- A dashboard with the same uid already exists, `status=name-exists`
+- The dashboard belongs to plugin `<plugin title>`, `status=plugin-dashboard`
+
+ The response body will have the following properties:
 
 ```http
 HTTP/1.1 412 Precondition Failed
@@ -85,16 +112,16 @@ Content-Length: 97
 
 In in case of title already exists the `status` property will be `name-exists`.
 
-## Get dashboard
+## Get dashboard by uid
 
-`GET /api/dashboards/db/:slug`
+`GET /api/dashboards/uid/:uid`
 
-Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title.
+Will return the dashboard given the dashboard unique identifier (uid).
 
 **Example Request**:
 
 ```http
-GET /api/dashboards/db/production-overview HTTP/1.1
+GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -107,12 +134,9 @@ HTTP/1.1 200
 Content-Type: application/json
 
 {
-  "meta": {
-    "isStarred": false,
-    "slug": "production-overview"
-  },
   "dashboard": {
-    "id": null,
+    "id": 1,
+    "uid": "cIBgcSjkk",
     "title": "Production Overview",
     "tags": [ "templated" ],
     "timezone": "browser",
@@ -122,20 +146,32 @@ Content-Type: application/json
     ],
     "schemaVersion": 6,
     "version": 0
+  },
+  "meta": {
+    "isStarred": false,
+    "url": "/d/cIBgcSjkk/production-overview",
+    "slug": "production-overview" //deprecated in Grafana v5.0
   }
 }
 ```
 
-## Delete dashboard
+Status Codes:
 
-`DELETE /api/dashboards/db/:slug`
+- **200** – Found
+- **401** – Unauthorized
+- **403** – Access denied
+- **404** – Not found
 
-The above will delete the dashboard with the specified slug. The slug is the url friendly (unique) version of the dashboard title.
+## Delete dashboard by uid
+
+`DELETE /api/dashboards/uid/:uid`
+
+Will delete the dashboard given the specified unique identifier (uid).
 
 **Example Request**:
 
 ```http
-DELETE /api/dashboards/db/test HTTP/1.1
+DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -147,9 +183,16 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"title": "Test"}
+{"title": "Production Overview"}
 ```
 
+Status Codes:
+
+- **200** – Deleted
+- **401** – Unauthorized
+- **403** – Access denied
+- **404** – Not found
+
 ## Gets the home dashboard
 
 `GET /api/dashboards/home`
@@ -172,15 +215,6 @@ HTTP/1.1 200
 Content-Type: application/json
 
 {
-  "meta":	{
-    "isHome":true,
-    "canSave":false,
-    "canEdit":false,
-    "canStar":false,
-    "slug":"",
-    "expires":"0001-01-01T00:00:00Z",
-    "created":"0001-01-01T00:00:00Z"
-  },
   "dashboard": {
     "editable":false,
     "hideControls":true,
@@ -206,13 +240,21 @@ Content-Type: application/json
     "timezone":"browser",
     "title":"Home",
     "version":5
+  },
+  "meta":	{
+    "isHome":true,
+    "canSave":false,
+    "canEdit":false,
+    "canStar":false,
+    "url":"",
+    "expires":"0001-01-01T00:00:00Z",
+    "created":"0001-01-01T00:00:00Z"
   }
 }
 ```
 
 ## Tags for Dashboard
 
-
 `GET /api/dashboards/tags`
 
 Get all tags of dashboards
@@ -244,21 +286,24 @@ Content-Type: application/json
 ]
 ```
 
-## Search Dashboards
+## Dashboard Search
+See [Folder/Dashboard Search API](/http_api/folder_dashboard_search).
 
-`GET /api/search/`
+## Deprecated resources
+Please note that these resource have been deprecated and will be removed in a future release.
 
-Query parameters:
+### Get dashboard by slug
+**Deprecated starting from Grafana v5.0. Please update to use the new *Get dashboard by uid* resource instead**
 
-- **query** – Search Query
+`GET /api/dashboards/db/:slug`
-- **tag** – Tag to use
+
-- **starred** – Flag indicating if only starred Dashboards should be returned
+Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title.
-- **tagcloud** - Flag indicating if a tagcloud should be returned
+If there exists multiple dashboards with the same slug, one of them will be returned in the response.
 
 **Example Request**:
 
 ```http
-GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1
+GET /api/dashboards/db/production-overview HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -270,14 +315,78 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-[
+{
-  {
+  "dashboard": {
-    "id":1,
+    "id": 1,
-    "title":"Production Overview",
+    "uid": "cIBgcSjkk",
-    "uri":"db/production-overview",
+    "title": "Production Overview",
-    "type":"dash-db",
+    "tags": [ "templated" ],
-    "tags":[prod],
+    "timezone": "browser",
-    "isStarred":true
+    "rows": [
+      {
+      }
+    ],
+    "schemaVersion": 6,
+    "version": 0
+  },
+  "meta": {
+    "isStarred": false,
+    "url": "/d/cIBgcSjkk/production-overview",
+    "slug": "production-overview" // deprecated in Grafana v5.0
   }
-]
+}
+```
+
+Status Codes:
+
+- **200** – Found
+- **401** – Unauthorized
+- **403** – Access denied
+- **404** – Not found
+
+### Delete dashboard by slug
+**Deprecated starting from Grafana v5.0. Please update to use the *Delete dashboard by uid* resource instead.**
+
+`DELETE /api/dashboards/db/:slug`
+
+Will delete the dashboard given the specified slug. Slug is the url friendly version of the dashboard title.
+
+**Example Request**:
+
+```http
+DELETE /api/dashboards/db/test HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{"title": "Production Overview"}
+```
+
+Status Codes:
+
+- **200** – Deleted
+- **401** – Unauthorized
+- **403** – Access denied
+- **404** – Not found
+- **412** – Precondition failed
+
+The **412** status code is used when there exists multiple dashboards with the same slug.
+The response body will look like this:
+
+```http
+HTTP/1.1 412 Precondition Failed
+Content-Type: application/json; charset=UTF-8
+Content-Length: 97
+
+{
+  "message": "Multiple dashboards with the same slug exists",
+  "status": "multiple-slugs-exists"
+}
 ```

docs/sources/http_api/folder_dashboard_search.md

@@ -0,0 +1,98 @@
++++
+title = "Folder/Dashboard Search HTTP API "
+description = "Grafana Folder/Dashboard Search HTTP API"
+keywords = ["grafana", "http", "documentation", "api", "search", "folder", "dashboard"]
+aliases = ["/http_api/folder_dashboard_search/"]
+type = "docs"
+[menu.docs]
+name = "Folder/dashboard search"
+parent = "http_api"
++++
+
+# Folder/Dashboard Search API
+
+## Search folders and dashboards
+
+`GET /api/search/`
+
+Query parameters:
+
+- **query** – Search Query
+- **tag** – List of tags to search for
+- **type** – Type to search for, `dash-folder` or `dash-db`
+- **dashboardIds** – List of dashboard id's to search for
+- **folderIds** – List of folder id's to search in for dashboards
+- **starred** – Flag indicating if only starred Dashboards should be returned
+- **limit** – Limit the number of returned results
+
+**Example request for retrieving folders and dashboards of the general folder**:
+
+```http
+GET /api/search?folderIds=0&query=&starred=false HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example response for retrieving folders and dashboards of the general folder**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+[
+  {
+    "id": 163,
+    "uid": "000000163",
+    "title": "Folder",
+    "url": "/dashboards/f/000000163/folder",
+    "type": "dash-folder",
+    "tags": [],
+    "isStarred": false,
+    "uri":"db/folder" // deprecated in Grafana v5.0
+  },
+  {
+    "id":1,
+    "uid": "cIBgcSjkk",
+    "title":"Production Overview",
+    "url": "/d/cIBgcSjkk/production-overview",
+    "type":"dash-db",
+    "tags":[prod],
+    "isStarred":true,
+    "uri":"db/production-overview" // deprecated in Grafana v5.0
+  }
+]
+```
+
+**Example request searching for dashboards**:
+
+```http
+GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example response searching for dashboards**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+[
+  {
+    "id":1,
+    "uid": "cIBgcSjkk",
+    "title":"Production Overview",
+    "url": "/d/cIBgcSjkk/production-overview",
+    "type":"dash-db",
+    "tags":[prod],
+    "isStarred":true,
+    "folderId": 2,
+    "folderUid": "000000163",
+    "folderTitle": "Folder",
+    "folderUrl": "/dashboards/f/000000163/folder",
+    "uri":"db/production-overview" // deprecated in Grafana v5.0
+  }
+]
+```

docs/sources/http_api/index.md

@@ -21,6 +21,7 @@ dashboards, creating users and updating data sources.
 * [Authentication API]({{< relref "/http_api/auth.md" >}})
 * [Dashboard API]({{< relref "/http_api/dashboard.md" >}})
 * [Dashboard Versions API]({{< relref "http_api/dashboard_versions.md" >}})
+* [Folder/dashboard search API]({{< relref "/http_api/folder_dashboard_search.md" >}})
 * [Data Source API]({{< relref "http_api/data_source.md" >}})
 * [Organisation API]({{< relref "http_api/org.md" >}})
 * [Snapshot API]({{< relref "http_api/snapshot.md" >}})