mirror of
https://github.com/grafana/grafana.git
synced 2025-07-30 11:12:30 +08:00
4ecd57f49c
* feature toggles * return HTTP 207 from ds/query * add ft check * add API test * add 207 check for qr * change to OR * revert check * add explicit toggle check for cloudwatch * remove unused import * remove from defaults.ini * add status codes to md and update swagger * new fangled http api tests pattern * update swagger * Update docs/sources/http_api/data_source.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * add missing word and reformat Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
817 lines
22 KiB
Markdown
817 lines
22 KiB
Markdown
+++
|
||
title = "Data source HTTP API "
|
||
description = "Grafana Data source HTTP API"
|
||
keywords = ["grafana", "http", "documentation", "api", "data source"]
|
||
aliases = ["/docs/grafana/latest/http_api/datasource/"]
|
||
+++
|
||
|
||
# Data source API
|
||
|
||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||
> Refer to specific resources to understand what permissions are required.
|
||
|
||
## Get all data sources
|
||
|
||
`GET /api/datasources`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | -------------- |
|
||
| datasources:read | datasources:\* |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Get a single data source by Id
|
||
|
||
`GET /api/datasources/:datasourceId`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ---------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/datasources/1 HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Get a single data source by UID
|
||
|
||
`GET /api/datasources/uid/:uid`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | -------------------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example request:**
|
||
|
||
```http
|
||
GET /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Get a single data source by Name
|
||
|
||
`GET /api/datasources/name/:name`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ---------------------------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/datasources/name/test_datasource HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Get data source Id by Name
|
||
|
||
`GET /api/datasources/id/:name`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| datasources.id:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/datasources/id/test_datasource HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Create a data source
|
||
|
||
`POST /api/datasources`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ----- |
|
||
| datasources:create | n/a |
|
||
|
||
### Examples
|
||
|
||
**Example Graphite Request**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
**Example Graphite Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
> **Note:** By defining `password` and `basicAuthPassword` under `secureJsonData` Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields under `secureJsonFields`.
|
||
|
||
**Example Graphite Request with basic auth enabled**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
**Example Response with basic auth enabled**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
**Example CloudWatch Request**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
## Update an existing data source
|
||
|
||
`PUT /api/datasources/:datasourceId`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ----------------- | ---------------------------------------------------------------------------- |
|
||
| datasources:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
PUT /api/datasources/1 HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
> **Note:** Similar to [creating a data source](#create-a-data-source), `password` and `basicAuthPassword` should be defined under `secureJsonData` in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under `secureJsonFields` section in the response.
|
||
|
||
## Delete an existing data source by id
|
||
|
||
`DELETE /api/datasources/:datasourceId`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ---------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
DELETE /api/datasources/1 HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Delete an existing data source by UID
|
||
|
||
`DELETE /api/datasources/uid/:uid`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | -------------------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example request:**
|
||
|
||
```http
|
||
DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Delete an existing data source by name
|
||
|
||
`DELETE /api/datasources/name/:datasourceName`
|
||
|
||
### Required permissions
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ---------------------------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
DELETE /api/datasources/name/test_datasource HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Data source proxy calls
|
||
|
||
`GET /api/datasources/proxy/:datasourceId/*`
|
||
|
||
Proxies all calls to the actual data source.
|
||
|
||
## Query a data source
|
||
|
||
Queries a data source having a backend implementation.
|
||
|
||
`POST /api/ds/query`
|
||
|
||
> **Note:** Grafana's built-in data sources usually have a backend implementation.
|
||
|
||
**Example request for the Test data source**:
|
||
|
||
```http
|
||
POST /api/ds/query HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
JSON Body schema:
|
||
|
||
- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`.
|
||
- **queries** – Specifies one or more queries. Must contain at least 1.
|
||
- **queries.datasource.uid** – Specifies the UID of data source to be queried. Each query in the request must have a unique `datasource`.
|
||
- **queries.refId** – Specifies an identifier of the query. Defaults to "A".
|
||
- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source.
|
||
- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100.
|
||
- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000.
|
||
|
||
In addition, specific properties of each data source should be added in a request (for example **queries.stringInput** as shown in the request above). To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/ds/query`.
|
||
|
||
**Example Test data source time series query response:**
|
||
|
||
```json
|
||
{
|
||
"results": {
|
||
"A": {
|
||
"frames": [
|
||
{
|
||
"schema": {
|
||
"refId": "A",
|
||
"fields": [
|
||
{
|
||
"name": "time",
|
||
"type": "time",
|
||
"typeInfo": {
|
||
"frame": "time.Time"
|
||
}
|
||
},
|
||
{
|
||
"name": "A-series",
|
||
"type": "number",
|
||
"typeInfo": {
|
||
"frame": "int64",
|
||
"nullable": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"data": {
|
||
"values": [
|
||
[1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
|
||
[1, 20, 90, 30, 5, 0]
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Status codes
|
||
|
||
| Code | Description |
|
||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 200 | All data source queries returned a successful response. |
|
||
| 400 | Bad request due to invalid JSON, missing content type, missing or invalid fields, etc. Or one or more data source queries were unsuccessful. Refer to the body for more details. |
|
||
| 403 | Access denied. |
|
||
| 404 | Either the data source or plugin required to fulfil the request could not be found. |
|
||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||
|
||
## Deprecated resources
|
||
|
||
The following resources have been deprecated. They will be removed in a future release.
|
||
|
||
### Query a data source by ID
|
||
|
||
> **Warning:** This API is deprecated since Grafana v8.5.0 and will be removed in a future release. Refer to the [new data source query API](#query-a-data-source-by-id).
|
||
|
||
Queries a data source having a backend implementation.
|
||
|
||
`POST /api/tsdb/query`
|
||
|
||
> **Note:** Grafana's built-in data sources usually have a backend implementation.
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
POST /api/tsdb/query HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
JSON Body schema:
|
||
|
||
- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`.
|
||
- **queries.refId** – Specifies an identifier of the query. Defaults to "A".
|
||
- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source.
|
||
- **queries.datasourceId** – Specifies the data source to be queried. Each `query` in the request must have a unique `datasourceId`.
|
||
- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100.
|
||
- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000.
|
||
|
||
In addition, specific properties of each data source should be added in a request. To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/tsdb/query`.
|
||
|
||
**Example request for the MySQL data source:**
|
||
|
||
```http
|
||
POST /api/tsdb/query HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
**Example MySQL time series query response:**
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|