From e9971dd153f4c440bf40abdbc6f6a59bc2930586 Mon Sep 17 00:00:00 2001 From: Michael Mandrus <41969079+mmandrus@users.noreply.github.com> Date: Thu, 27 Apr 2023 10:28:26 -0400 Subject: [PATCH] Docs: Create documentation for enterprise caching HTTP API (#67169) * create http docs for query caching * fix endpoints * Update docs/sources/developers/http_api/query_and_resource_caching.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * run prettier * super small change to reflect incoming API update --------- Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> --- docs/sources/developers/http_api/_index.md | 1 + .../http_api/query_and_resource_caching.md | 295 ++++++++++++++++++ 2 files changed, 296 insertions(+) create mode 100644 docs/sources/developers/http_api/query_and_resource_caching.md diff --git a/docs/sources/developers/http_api/_index.md b/docs/sources/developers/http_api/_index.md index 711aa1655bb..f84bb4c09d5 100644 --- a/docs/sources/developers/http_api/_index.md +++ b/docs/sources/developers/http_api/_index.md @@ -65,3 +65,4 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as those that fo - [External group sync API]({{< relref "external_group_sync/" >}}) - [License API]({{< relref "licensing/" >}}) - [Reporting API]({{< relref "reporting/" >}}) +- [Query and resource caching API]({{< relref "query_and_resource_caching/" >}}) diff --git a/docs/sources/developers/http_api/query_and_resource_caching.md b/docs/sources/developers/http_api/query_and_resource_caching.md new file mode 100644 index 00000000000..84bfe4fdbee --- /dev/null +++ b/docs/sources/developers/http_api/query_and_resource_caching.md @@ -0,0 +1,295 @@ +--- +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 + +> **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. + +## 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 + +{ + "message": "Data source cache enabled", + "dataSourceID": 1, + "dataSourceUID": "jZrmlLCGka", + "enabled": true, + "ttlQueriesMs": 300000, + "ttlResourcesMs": 300000, + "useDefaultTTL": true, + "defaultTTLMs": 300000, + "created": "2023-04-21T11:49:22-04:00", + "updated": "2023-04-24T16:30:29-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. | + +## 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 + +{ + "message": "Data source cache disabled", + "dataSourceID": 1, + "dataSourceUID": "jZrmlLCGka", + "enabled": false, + "ttlQueriesMs": 300000, + "ttlResourcesMs": 300000, + "useDefaultTTL": true, + "defaultTTLMs": 0, + "created": "2023-04-21T11:49:22-04:00", + "updated": "2023-04-24T16:30:31-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. | + +## 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 + +{ + "message": "Data source cache cleaned", + "dataSourceID": 1, + "dataSourceUID": "jZrmlLCGka", + "enabled": false, + "ttlQueriesMs": 300000, + "ttlResourcesMs": 300000, + "useDefaultTTL": true, + "defaultTTLMs": 0, + "created": "2023-04-21T11:49:22-04:00", + "updated": "2023-04-24T16:30:31-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. | + +## 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 + +{ + "dataSourceID": 1, + "dataSourceUID": "jZrmlLCGka", + "enabled": true, + "useDefaultTTL": false, + "ttlQueriesMs": 60000, + "ttlResourcesMs": 300000, +} +``` + +#### 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 + +{ + "message": "Data source cache settings updated", + "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 | +| 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. |