public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[v9.4.x] [feat] docs; update admonition syntax (#68855)

Browse Source 
[feat] docs; update admonition syntax (#68842)

* [feat] docs; update admonition syntax

- Standardizes according to style conventions: https://grafana.com/docs/writers-toolkit/style-guide/style-conventions/#admonitions
- Prepares docs for better, uniform admonition style.

* Remove false positives and irregularities

* false positive removal

* Update docs/sources/datasources/mysql/_index.md

* Update docs/sources/developers/angular_deprecation/angular-plugins.md

* fix link errors

* Prettify some nested blockquotes

* remoe unnecessary admonition

(cherry picked from commit 1c4bb9ca00)

Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com>
This commit is contained in:
Grot (@grafanabot)
2023-05-23 13:46:19 +01:00
committed by GitHub
parent ad2a920191
commit 048de5d09a
144 changed files with 3887 additions and 1238 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/developers/http_api/admin.md
+6 -2
View File
@@ -192,7 +192,9 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
## Password for User
```
## Password for User
`PUT /api/admin/users/:id/password`
@@ -471,7 +473,9 @@ Content-Type: application/json
Reloads the LDAP configuration.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
**Example Request**:
```http
POST /api/admin/ldap/reload HTTP/1.1
Accept: application/json
docs/sources/developers/http_api/alerting.md
+3 -1
View File
@@ -15,7 +15,9 @@ title: 'Alerting HTTP API '
# Legacy Alerting API
> **Note:** Starting with v9.0, the Legacy Alerting HTTP API is deprecated. It will be removed in a future release.
{{% admonition type="note" %}}
Starting with v9.0, the Legacy Alerting HTTP API is deprecated. It will be removed in a future release.
{{% /admonition %}}
This topic is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only.
docs/sources/developers/http_api/alerting_notification_channels.md
+3 -1
View File
@@ -16,7 +16,9 @@ title: 'Alerting Notification Channels HTTP API '
# Legacy Alerting Notification Channels API
> **Note:** Starting with v9.0, the Legacy Alerting Notification Channels API is deprecated. It will be removed in a future release.
{{% admonition type="note" %}}
Starting with v9.0, the Legacy Alerting Notification Channels API is deprecated. It will be removed in a future release.
{{% /admonition %}}
This page documents the Alerting Notification Channels API.
docs/sources/developers/http_api/dashboard_permissions.md
+6 -2
View File
@@ -176,7 +176,9 @@ Status Codes:
- **403** - Access denied
- **404** - Dashboard not found
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
## Update permissions for a dashboard by id
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
{{% /admonition %}}
@@ -257,7 +259,9 @@ Status Codes:
## Update permissions for a dashboard by id
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
{{% /admonition %}}
`POST /api/dashboards/id/:dashboardId/permissions`
docs/sources/developers/http_api/dashboard_versions.md
+9 -3
View File
@@ -18,7 +18,9 @@ title: 'Dashboard Versions HTTP API '
## Get all dashboard versions
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard versions API](#get-all-dashboard-versions-by-dashboard-uid).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard versions API](#get-all-dashboard-versions-by-dashboard-uid).
{{% /admonition %}}
Query parameters:
@@ -138,7 +140,9 @@ Status Codes:
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
@@ -363,7 +367,9 @@ Status Codes:
## Restore dashboard
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new restore dashboard API](#restore-dashboard-by-dashboard-uid).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new restore dashboard API](#restore-dashboard-by-dashboard-uid).
{{% /admonition %}}
`POST /api/dashboards/id/:dashboardId/restore`
docs/sources/developers/http_api/data_source.md
+27 -9
View File
@@ -77,7 +77,9 @@ Content-Type: application/json
**Example Response**:
Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
```
@@ -342,7 +344,9 @@ Content-Type: application/json
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
@@ -429,7 +433,9 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source health check API](#check-data-source-health).
Accept: application/json
`GET /api/datasources/:datasourceId/health`
Makes a call to the health endpoint of data source identified by the given `datasourceId`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves.
### Examples
@@ -506,7 +512,9 @@ Content-Type: application/json
## Fetch data source resources
Accept: application/json
`GET /api/datasources/uid/:uid/resources/*`
Makes a call to the resources endpoint of data source identified by the given `uid`.
### Examples
@@ -588,13 +596,17 @@ Content-Type: application/json
},
"data": {
"values": [
[1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
[1, 20, 90, 30, 5, 0]
]
}
}
]
}
}
| 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. |
}
```
#### Status codes
| Code | Description |
@@ -696,7 +708,9 @@ Content-Type: application/json
## Data source proxy calls by id
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source API for proxying requests](#data-source-proxy-calls).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source API for proxying requests](#data-source-proxy-calls).
{{% /admonition %}}
`GET /api/datasources/proxy/:datasourceId/*`
@@ -770,7 +784,9 @@ Content-Type: application/json
## Fetch data source resources by id
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source resources API](#fetch-data-source-resources).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source resources API](#fetch-data-source-resources).
{{% /admonition %}}
`GET /api/datasources/:datasourceId/resources/*`
@@ -870,7 +886,9 @@ Queries a data source having a backend implementation.
`POST /api/ds/query`
> **Note:** Grafana's built-in data sources usually have a backend implementation.
{{% admonition type="note" %}}
Grafana's built-in data sources usually have a backend implementation.
{{% /admonition %}}
**Example request for the Test data source**:
docs/sources/developers/http_api/library_element.md
+3 -1
View File
@@ -437,7 +437,9 @@ Status Codes:
Deletes an existing library element as specified by the UID. This operation cannot be reverted.
> **Note:** You cannot delete a library element that is connected. This operation cannot be reverted.
{{% admonition type="note" %}}
You cannot delete a library element that is connected. This operation cannot be reverted.
{{% /admonition %}}
**Example Request**:
docs/sources/developers/http_api/licensing.md
+9 -3
View File
@@ -61,7 +61,9 @@ Status codes:
## Add license
{{% admonition type="note" %}}
Available in Grafana Enterprise v7.4+.
{{% /admonition %}}
`POST /api/licensing/token`
Applies a license to a Grafana instance.
@@ -121,7 +123,9 @@ Status Codes:
| Action | Scope |
| --------------- | ----- |
### Examples
| licensing:write | n/a |
### Examples
**Example request:**
@@ -180,7 +184,9 @@ Status Codes:
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{"instance": "http://play.grafana.org/"}
```
JSON Body schema:
- **instance** – Root URL for the instance for which the license should be deleted. Required.
docs/sources/developers/http_api/query_and_resource_caching.md
+297
View File
@@ -0,0 +1,297 @@
---
aliases:
- ../../http_api/query_caching/
- ../../http_api/resource_caching/
- ../../http_api/caching/
canonical: /docs/grafana/latest/developers/http_api/query_and_resource_caching/
description: Grafana Enterprise Query and Resource Caching HTTP API
keywords:
- grafana
- http
- documentation
- api
- caching
- query caching
- resource caching
- data source
title: Query and Resource Caching HTTP API
---
# Query and resource caching API
{{% admonition type="note" %}}
If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
{{% /admonition %}}
## Enable caching for a data source
`POST /api/datasources/:dataSourceUID/cache/enable`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/enable 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
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Disable caching for a data source
`POST /api/datasources/:dataSourceUID/cache/disable`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/disable 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
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Clean cache for all data sources
`POST /api/datasources/:dataSourceUID/cache/clean`
Will clean cached data for _all_ data sources with caching enabled. The `dataSourceUID` specified will only be used to return the configuration for that data source.
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/clean 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
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Update cache configuration for a data source
`POST /api/datasources/:dataSourceUID/cache`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
#### JSON Body Schema
| Field name | Data type | Description |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| dataSourceID | number | The ID of the data source to configure. |
| dataSourceUID | string | The UID of the data source to configure. |
| enabled | boolean | Whether or not to enable caching for this data source. |
| useDefaultTTL | boolean | Whether the configured default TTL (Time-To-Live) should be used for both query and resource caching, instead of the user-specified values. |
| ttlQueriesMs | number | The TTL to use for query caching, in milliseconds. |
| ttlResourcesMs | number | The TTL to use for resource caching, in milliseconds. |
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Get cache configuration for a data source
`GET /api/datasources/:dataSourceUID/cache`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------ | -------------- |
| datasources.caching:read | datasources:\* |
### Examples
**Example Request**:
```http
GET /api/datasources/jZrmlLCGka/cache 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
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"useDefaultTTL": false,
"ttlQueriesMs": 60000,
"ttlResourcesMs": 300000,
"defaultTTLMs": 300000,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T17:03:40-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Get cache configuration for a data source
`GET /api/datasources/:dataSourceUID/cache`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------ | -------------- |
| datasources.caching:read | datasources:\* |
### Examples
**Example Request**:
```http
GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache settings loaded",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"useDefaultTTL": false,
"ttlQueriesMs": 60000,
"ttlResourcesMs": 300000,
"defaultTTLMs": 300000,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T17:03:40-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
docs/sources/developers/http_api/snapshot.md
+3 -1
View File
@@ -65,7 +65,9 @@ JSON Body schema:
- **key** - Optional. Define the unique key. Required if **external** is `true`.
- **deleteKey** - Optional. Unique key used to delete the snapshot. It is different from the **key** so that only the creator can delete the snapshot. Required if **external** is `true`.
> **Note:** When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI.
{{% admonition type="note" %}}
When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI.
{{% /admonition %}}
**Example Response**: