mirror of
https://github.com/grafana/grafana.git
synced 2025-07-31 09:32:40 +08:00
docs: update http api for api index, dashboard, folder and dashboard search
This commit is contained in:
Marcus Efraimsson
@ -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
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **dashboard** – The complete dashboard model, id = null to create a new dashboard.
|
||||
- **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.
|
||||
@ -38,14 +50,18 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 78
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
- **200** – Created
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
|
||||
- **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 for explaing that you cannot create the dashboard and why.
|
||||
@ -56,9 +72,12 @@ Content-Type: application/json; charset=UTF-8
|
||||
- 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
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 97
|
||||
|
||||
```
|
||||
|
||||
@ -67,10 +86,18 @@ Status Codes:
|
||||
## Get dashboard by uid
|
||||
|
||||
`GET /api/dashboards/uid/:uid`
|
||||
|
||||
Will return the dashboard given the dashboard unique identifier (uid).
|
||||
|
||||
```http
|
||||
GET /api/dashboards/db/production-overview HTTP/1.1
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
@ -85,16 +112,16 @@ Content-Length: 97
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
|
||||
|
||||
## Delete dashboard by uid
|
||||
|
||||
|
||||
`DELETE /api/dashboards/uid/:uid`
|
||||
|
||||
|
||||
Will delete the dashboard given the specified unique identifier (uid).
|
||||
|
||||
**Example Request**:
|
||||
|
||||
Accept: application/json
|
||||
```http
|
||||
DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
@ -107,12 +134,9 @@ HTTP/1.1 200
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
## Gets the home dashboard
|
||||
|
||||
`GET /api/dashboards/home`
|
||||
|
||||
```
|
||||
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
@ -122,20 +146,32 @@ Content-Type: application/json
|
||||
## Gets the home dashboard
|
||||
|
||||
`GET /api/dashboards/home`
|
||||
|
||||
Will return the home dashboard.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/home HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
## Tags for Dashboard
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Tags for Dashboard
|
||||
|
||||
`GET /api/dashboards/tags`
|
||||
|
||||
Get all tags of dashboards
|
||||
Get all tags of dashboards
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@ -147,9 +183,16 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
**Example Response**:
|
||||
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Dashboard Search
|
||||
See [Folder/Dashboard Search API](/http_api/folder_dashboard_search).
|
||||
|
||||
## Deprecated resources
|
||||
Please note that these resource have been deprecated and will be removed in a future release.
|
||||
|
||||
### Get dashboard by slug
|
||||
@ -172,15 +215,6 @@ HTTP/1.1 200
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
@ -206,13 +240,21 @@ Content-Type: application/json
|
||||
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
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
- **412** – Precondition failed
|
||||
@ -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
|
||||
- **tag** – Tag to use
|
||||
- **starred** – Flag indicating if only starred Dashboards should be returned
|
||||
- **tagcloud** - Flag indicating if a tagcloud should be returned
|
||||
`GET /api/dashboards/db/:slug`
|
||||
|
||||
Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title.
|
||||
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
|
||||
|
||||
[
|
||||
{
|
||||
"id":1,
|
||||
"title":"Production Overview",
|
||||
"uri":"db/production-overview",
|
||||
"type":"dash-db",
|
||||
"tags":[prod],
|
||||
"isStarred":true
|
||||
{
|
||||
"dashboard": {
|
||||
"id": 1,
|
||||
"uid": "cIBgcSjkk",
|
||||
"title": "Production Overview",
|
||||
"tags": [ "templated" ],
|
||||
"timezone": "browser",
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
98
docs/sources/http_api/folder_dashboard_search.md
Normal file
98
docs/sources/http_api/folder_dashboard_search.md
Normal file
@ -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
|
||||
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
```
|
||||
"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
|
||||
}
|
||||
]
|
||||
```
|
||||
@ -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" >}})
|
||||
|
||||
Reference in New Issue
Block a user