From 0ddb3b752108c4cd0d01ce4c417837f22d4d5385 Mon Sep 17 00:00:00 2001 From: Ivana Huckova <30407135+ivanahuckova@users.noreply.github.com> Date: Mon, 13 Jun 2022 09:47:40 +0200 Subject: [PATCH] Query history: Add swagger definitions (#50498) * Query history: Add swagger definitions * Update * Remove changes in generated files * Generate api files * Add query history into api docs * Add examples for commands * Add missing parameters * Generate api-spec and api-merged * Fix linting * Fix showing of example of queries * Revert "Fix showing of example of queries" This reverts commit b1eb073fbe26fd41351226dde7bdca33838c78f7. * Update * Update --- docs/sources/developers/http_api/_index.md | 1 + .../developers/http_api/query_history.md | 77 ++- pkg/api/docs/definitions/query_history.go | 179 +++++++ pkg/api/docs/tags.json | 4 + pkg/services/queryhistory/api.go | 9 +- pkg/services/queryhistory/database.go | 7 + pkg/services/queryhistory/models.go | 44 +- public/api-merged.json | 473 +++++++++++++++++- public/api-spec.json | 473 +++++++++++++++++- 9 files changed, 1211 insertions(+), 56 deletions(-) create mode 100644 pkg/api/docs/definitions/query_history.go diff --git a/docs/sources/developers/http_api/_index.md b/docs/sources/developers/http_api/_index.md index 6ea19b3df63..65827a1aeee 100644 --- a/docs/sources/developers/http_api/_index.md +++ b/docs/sources/developers/http_api/_index.md @@ -38,6 +38,7 @@ dashboards, creating users, and updating data sources. - [Playlists API]({{< relref "playlist/" >}}) - [Preferences API]({{< relref "preferences/" >}}) - [Short URL API]({{< relref "short_url/" >}}) +- [Query history API]({{< relref "query_history/" >}}) - [Snapshot API]({{< relref "snapshot/" >}}) - [Team API]({{< relref "team/" >}}) - [User API]({{< relref "user/" >}}) diff --git a/docs/sources/developers/http_api/query_history.md b/docs/sources/developers/http_api/query_history.md index b7616fb1ba8..2f1dd8cb71f 100644 --- a/docs/sources/developers/http_api/query_history.md +++ b/docs/sources/developers/http_api/query_history.md @@ -82,7 +82,8 @@ Status codes: - **200** – OK - **400** - Errors (invalid JSON, missing or invalid fields) -- **500** – Unable to add query to the database +- **401** – Unauthorized +- **500** – Internal error ## Query history search @@ -144,7 +145,8 @@ Content-Type: application/json Status codes: - **200** – OK -- **500** – Unable to add query to the database +- **401** – Unauthorized +- **500** – Internal error ## Delete query from Query history by UID @@ -176,7 +178,8 @@ Content-Type: application/json Status codes: - **200** – OK -- **500** – Unable to delete query from the database +- **401** – Unauthorized +- **500** – Internal error ## Update comment of query in Query history by UID @@ -232,7 +235,8 @@ Status codes: - **200** – OK - **400** - Errors (invalid JSON, missing or invalid fields) -- **500** – Unable to update comment of query in the database +- **401** – Unauthorized +- **500** – Internal error ## Star query in Query history @@ -280,7 +284,8 @@ Content-Type: application/json Status codes: - **200** – OK -- **500** – Unable to star query in the database +- **401** – Unauthorized +- **500** – Internal error ## Unstar query in Query history @@ -328,4 +333,64 @@ Content-Type: application/json Status codes: - **200** – OK -- **500** – Unable to unstar query in the database +- **401** – Unauthorized +- **500** – Internal error + +## Migrate queries to Query history + +`POST /api/query-history/migrate` + +Migrates multiple queries in to query history. + +**Example request:** + +```http +POST /api/query-history HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "queries": [ + { + "datasourceUid": "PE1C5CBDA0504A6A3", + "queries": [ + { + "refId": "A", + "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0", + "scenarioId": "csv_content", + "datasource": { + "type": "testdata", + "uid": "PD8C576611E62080A" + } + } + ], + "starred": false, + "createdAt": 1643630762, + "comment": "debugging" + } + ] +} +``` + +JSON body schema: + +- **queries** – JSON of query history items. + +**Example response:** + +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "message": "Query history successfully migrated", + "totalCount": 105, + "starredCount": 10 +} +``` + +Status codes: + +- **200** – OK +- **400** - Errors (invalid JSON, missing or invalid fields) +- **401** – Unauthorized +- **500** – Internal error diff --git a/pkg/api/docs/definitions/query_history.go b/pkg/api/docs/definitions/query_history.go new file mode 100644 index 00000000000..12fc438477a --- /dev/null +++ b/pkg/api/docs/definitions/query_history.go @@ -0,0 +1,179 @@ +package definitions + +import ( + "github.com/grafana/grafana/pkg/services/queryhistory" +) + +// swagger:route GET /query-history query_history searchQueries +// +// Query history search. +// +// Returns a list of queries in the query history that matches the search criteria. +// Query history search supports pagination. Use the `limit` parameter to control the maximum number of queries returned; the default limit is 100. +// You can also use the `page` query parameter to fetch queries from any page other than the first one. +// +// Responses: +// 200: getQueryHistorySearchResponse +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route POST /query-history query_history createQuery +// +// Add query to query history. +// +// Adds new query to query history. +// +// Responses: +// 200: getQueryHistoryResponse +// 400: badRequestError +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route POST /query-history/star/{query_history_uid} query_history starQuery +// +// Add star to query in query history. +// +// Adds star to query in query history as specified by the UID. +// +// Responses: +// 200: getQueryHistoryResponse +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route POST /query-history/migrate query_history migrateQueries +// +// Migrate queries to query history. +// +// Adds multiple queries to query history. +// +// Responses: +// 200: getQueryHistoryMigrationResponse +// 400: badRequestError +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route PATCH /query-history/{query_history_uid} query_history patchQueryComment +// +// Update comment for query in query history. +// +// Updates comment for query in query history as specified by the UID. +// +// Responses: +// 200: getQueryHistoryResponse +// 400: badRequestError +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route DELETE /query-history/{query_history_uid} query_history deleteQuery +// +// Delete query in query history. +// +// Deletes an existing query in query history as specified by the UID. This operation cannot be reverted. +// +// Responses: +// 200: getQueryHistoryDeleteQueryResponse +// 401: unauthorisedError +// 500: internalServerError + +// swagger:route DELETE /query-history/star/{query_history_uid} query_history unstarQuery +// +// Remove star to query in query history. +// +// Removes star from query in query history as specified by the UID. +// +// Responses: +// 200: getQueryHistoryResponse +// 401: unauthorisedError +// 500: internalServerError + +// swagger:parameters starQuery patchQueryComment deleteQuery unstarQuery +type QueryHistoryByUID struct { + // in:path + // required:true + UID string `json:"query_history_uid"` +} + +// swagger:parameters searchQueries +type SearchQueriesParams struct { + // List of data source UIDs to search for + // in:query + // required: false + // type: array + // collectionFormat: multi + DatasourceUid []string `json:"datasourceUid"` + // Text inside query or comments that is searched for + // in:query + // required: false + SearchString string `json:"searchString"` + // Flag indicating if only starred queries should be returned + // in:query + // required: false + OnlyStarred bool `json:"onlyStarred"` + // Sort method + // in:query + // required: false + // default: time-desc + // Enum: time-desc,time-asc + Sort string `json:"sort"` + // Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size. + // in:query + // required: false + Page int `json:"page"` + // Limit the number of returned results + // in:query + // required: false + Limit int `json:"limit"` + // From range for the query history search + // in:query + // required: false + From int64 `json:"from"` + // To range for the query history search + // in:query + // required: false + To int64 `json:"to"` +} + +// swagger:parameters createQuery +type CreateQueryParams struct { + // in:body + // required:true + Body queryhistory.CreateQueryInQueryHistoryCommand `json:"body"` +} + +// swagger:parameters patchQueryComment +type PatchQueryCommentParams struct { + // in:body + // required:true + Body queryhistory.PatchQueryCommentInQueryHistoryCommand `json:"body"` +} + +// swagger:parameters migrateQueries +type MigrateQueriesParams struct { + // in:body + // required:true + Body queryhistory.MigrateQueriesToQueryHistoryCommand `json:"body"` +} + +//swagger:response getQueryHistorySearchResponse +type GetQueryHistorySearchResponse struct { + // in: body + Body queryhistory.QueryHistorySearchResponse `json:"body"` +} + +// swagger:response getQueryHistoryResponse +type GetQueryHistoryResponse struct { + // in: body + Body queryhistory.QueryHistoryResponse `json:"body"` +} + +// swagger:response getQueryHistoryDeleteQueryResponse +type GetQueryHistoryDeleteQueryResponse struct { + // in: body + Body queryhistory.QueryHistoryDeleteQueryResponse `json:"body"` +} + +// swagger:response getQueryHistoryMigrationResponse +type GetQueryHistoryMigrationResponse struct { + // in: body + Body queryhistory.QueryHistoryMigrationResponse `json:"body"` +} diff --git a/pkg/api/docs/tags.json b/pkg/api/docs/tags.json index 17b6bf9aa82..b46177db930 100644 --- a/pkg/api/docs/tags.json +++ b/pkg/api/docs/tags.json @@ -31,6 +31,10 @@ { "name": "library_elements", "description": "The identifier (ID) of a library element is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a library element uniquely identifies library elements between multiple Grafana installs. It’s automatically generated unless you specify it during library element creation. The UID provides consistent URLs for accessing library elements and when syncing library elements between multiple Grafana installs.\nThe maximum length of a UID is 40 characters." + }, + { + "name": "query_history", + "description": "The identifier (ID) of a query in query history is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a query history uniquely identifies queries in query history between multiple Grafana installs. It’s automatically generated. The UID provides consistent URLs for accessing queries in query history." }, { "name": "orgs", diff --git a/pkg/services/queryhistory/api.go b/pkg/services/queryhistory/api.go index eac4ca1667e..58881377ac1 100644 --- a/pkg/services/queryhistory/api.go +++ b/pkg/services/queryhistory/api.go @@ -25,6 +25,7 @@ func (s *QueryHistoryService) registerAPIEndpoints() { }) } +// createHandler handles POST /api/query-history func (s *QueryHistoryService) createHandler(c *models.ReqContext) response.Response { cmd := CreateQueryInQueryHistoryCommand{} if err := web.Bind(c.Req, &cmd); err != nil { @@ -39,6 +40,7 @@ func (s *QueryHistoryService) createHandler(c *models.ReqContext) response.Respo return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query}) } +// searchHandler handles GET /api/query-history func (s *QueryHistoryService) searchHandler(c *models.ReqContext) response.Response { timeRange := legacydata.NewDataTimeRange(c.Query("from"), c.Query("to")) @@ -61,6 +63,7 @@ func (s *QueryHistoryService) searchHandler(c *models.ReqContext) response.Respo return response.JSON(http.StatusOK, QueryHistorySearchResponse{Result: result}) } +// deleteHandler handles DELETE /api/query-history/:uid func (s *QueryHistoryService) deleteHandler(c *models.ReqContext) response.Response { queryUID := web.Params(c.Req)[":uid"] if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) { @@ -72,12 +75,13 @@ func (s *QueryHistoryService) deleteHandler(c *models.ReqContext) response.Respo return response.Error(http.StatusInternalServerError, "Failed to delete query from query history", err) } - return response.JSON(http.StatusOK, DeleteQueryFromQueryHistoryResponse{ + return response.JSON(http.StatusOK, QueryHistoryDeleteQueryResponse{ Message: "Query deleted", ID: id, }) } +// patchCommentHandler handles PATCH /api/query-history/:uid func (s *QueryHistoryService) patchCommentHandler(c *models.ReqContext) response.Response { queryUID := web.Params(c.Req)[":uid"] if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) { @@ -97,6 +101,7 @@ func (s *QueryHistoryService) patchCommentHandler(c *models.ReqContext) response return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query}) } +// starHandler handles POST /api/query-history/star/:uid func (s *QueryHistoryService) starHandler(c *models.ReqContext) response.Response { queryUID := web.Params(c.Req)[":uid"] if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) { @@ -111,6 +116,7 @@ func (s *QueryHistoryService) starHandler(c *models.ReqContext) response.Respons return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query}) } +// starHandler handles DELETE /api/query-history/star/:uid func (s *QueryHistoryService) unstarHandler(c *models.ReqContext) response.Response { queryUID := web.Params(c.Req)[":uid"] if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) { @@ -125,6 +131,7 @@ func (s *QueryHistoryService) unstarHandler(c *models.ReqContext) response.Respo return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query}) } +// starHandler handles POST /api/query-history/migrate func (s *QueryHistoryService) migrateHandler(c *models.ReqContext) response.Response { cmd := MigrateQueriesToQueryHistoryCommand{} if err := web.Bind(c.Req, &cmd); err != nil { diff --git a/pkg/services/queryhistory/database.go b/pkg/services/queryhistory/database.go index 1831615eef9..1db7c202cc6 100644 --- a/pkg/services/queryhistory/database.go +++ b/pkg/services/queryhistory/database.go @@ -11,6 +11,7 @@ import ( "github.com/grafana/grafana/pkg/util" ) +// createQuery adds a query into query history func (s QueryHistoryService) createQuery(ctx context.Context, user *models.SignedInUser, cmd CreateQueryInQueryHistoryCommand) (QueryHistoryDTO, error) { queryHistory := QueryHistory{ OrgID: user.OrgId, @@ -43,6 +44,7 @@ func (s QueryHistoryService) createQuery(ctx context.Context, user *models.Signe return dto, nil } +// searchQueries searches for queries in query history based on provided parameters func (s QueryHistoryService) searchQueries(ctx context.Context, user *models.SignedInUser, query SearchInQueryHistoryQuery) (QueryHistorySearchResult, error) { var dtos []QueryHistoryDTO var allQueries []interface{} @@ -132,6 +134,7 @@ func (s QueryHistoryService) deleteQuery(ctx context.Context, user *models.Signe return queryID, err } +// patchQueryComment searches updates comment for query in query history func (s QueryHistoryService) patchQueryComment(ctx context.Context, user *models.SignedInUser, UID string, cmd PatchQueryCommentInQueryHistoryCommand) (QueryHistoryDTO, error) { var queryHistory QueryHistory var isStarred bool @@ -176,6 +179,7 @@ func (s QueryHistoryService) patchQueryComment(ctx context.Context, user *models return dto, nil } +// starQuery adds query into query_history_star table together with user_id and org_id func (s QueryHistoryService) starQuery(ctx context.Context, user *models.SignedInUser, UID string) (QueryHistoryDTO, error) { var queryHistory QueryHistory var isStarred bool @@ -225,6 +229,7 @@ func (s QueryHistoryService) starQuery(ctx context.Context, user *models.SignedI return dto, nil } +// unstarQuery deletes query with with user_id and org_id from query_history_star table func (s QueryHistoryService) unstarQuery(ctx context.Context, user *models.SignedInUser, UID string) (QueryHistoryDTO, error) { var queryHistory QueryHistory var isStarred bool @@ -267,6 +272,7 @@ func (s QueryHistoryService) unstarQuery(ctx context.Context, user *models.Signe return dto, nil } +// migrateQueries adds multiple queries into query history func (s QueryHistoryService) migrateQueries(ctx context.Context, user *models.SignedInUser, cmd MigrateQueriesToQueryHistoryCommand) (int, int, error) { queryHistories := make([]*QueryHistory, 0, len(cmd.Queries)) starredQueries := make([]*QueryHistoryStar, 0) @@ -363,6 +369,7 @@ func (s QueryHistoryService) deleteStaleQueries(ctx context.Context, olderThan i return int(rowsCount), nil } +// enforceQueryHistoryRowLimit is run in scheduled cleanup and it removes queries and stars that exceeded limit func (s QueryHistoryService) enforceQueryHistoryRowLimit(ctx context.Context, limit int, starredQueries bool) (int, error) { var deletedRowsCount int64 diff --git a/pkg/services/queryhistory/models.go b/pkg/services/queryhistory/models.go index e930604725e..98d646365a6 100644 --- a/pkg/services/queryhistory/models.go +++ b/pkg/services/queryhistory/models.go @@ -12,6 +12,7 @@ var ( ErrQueryAlreadyStarred = errors.New("query was already starred") ) +// QueryHistory is the model for query history definitions type QueryHistory struct { ID int64 `xorm:"pk autoincr 'id'"` UID string `xorm:"uid"` @@ -23,17 +24,13 @@ type QueryHistory struct { Queries *simplejson.Json } +// QueryHistory is the model for query history star definitions type QueryHistoryStar struct { ID int64 `xorm:"pk autoincr 'id'"` QueryUID string `xorm:"query_uid"` UserID int64 `xorm:"user_id"` } -type CreateQueryInQueryHistoryCommand struct { - DatasourceUID string `json:"datasourceUid"` - Queries *simplejson.Json `json:"queries"` -} - type SearchInQueryHistoryQuery struct { DatasourceUIDs []string `json:"datasourceUids"` SearchString string `json:"searchString"` @@ -45,10 +42,6 @@ type SearchInQueryHistoryQuery struct { To int64 `json:"to"` } -type PatchQueryCommentInQueryHistoryCommand struct { - Comment string `json:"comment"` -} - type QueryHistoryDTO struct { UID string `json:"uid" xorm:"uid"` DatasourceUID string `json:"datasourceUid" xorm:"datasource_uid"` @@ -75,16 +68,12 @@ type QueryHistorySearchResponse struct { Result QueryHistorySearchResult `json:"result"` } -// DeleteQueryFromQueryHistoryResponse is the response struct for deleting a query from query history -type DeleteQueryFromQueryHistoryResponse struct { +// QueryHistoryDeleteQueryResponse is the response struct for deleting a query from query history +type QueryHistoryDeleteQueryResponse struct { ID int64 `json:"id"` Message string `json:"message"` } -type MigrateQueriesToQueryHistoryCommand struct { - Queries []QueryToMigrate `json:"queries"` -} - type QueryToMigrate struct { DatasourceUID string `json:"datasourceUid"` Queries *simplejson.Json `json:"queries"` @@ -98,3 +87,28 @@ type QueryHistoryMigrationResponse struct { TotalCount int `json:"totalCount"` StarredCount int `json:"starredCount"` } + +// CreateQueryInQueryHistoryCommand is the command for adding query history +// swagger:model +type CreateQueryInQueryHistoryCommand struct { + // UID of the data source for which are queries stored. + // example: PE1C5CBDA0504A6A3 + DatasourceUID string `json:"datasourceUid"` + // The JSON model of queries. + // required: true + Queries *simplejson.Json `json:"queries"` +} + +// PatchQueryCommentInQueryHistoryCommand is the command for updating comment for query in query history +// swagger:model +type PatchQueryCommentInQueryHistoryCommand struct { + // Updated comment + Comment string `json:"comment"` +} + +// MigrateQueriesToQueryHistoryCommand is the command used for migration of old queries into query history +// swagger:model +type MigrateQueriesToQueryHistoryCommand struct { + // Array of queries to store in query history. + Queries []QueryToMigrate `json:"queries"` +} diff --git a/public/api-merged.json b/public/api-merged.json index aa81d429ce8..2671e83809f 100644 --- a/public/api-merged.json +++ b/public/api-merged.json @@ -489,13 +489,6 @@ "summary": "Add a user role assignment.", "operationId": "addUserRole", "parameters": [ - { - "type": "integer", - "format": "int64", - "name": "user_id", - "in": "path", - "required": true - }, { "name": "body", "in": "body", @@ -503,6 +496,13 @@ "schema": { "$ref": "#/definitions/AddUserRoleCommand" } + }, + { + "type": "integer", + "format": "int64", + "name": "user_id", + "in": "path", + "required": true } ], "responses": { @@ -528,13 +528,6 @@ "summary": "Remove a user role assignment.", "operationId": "removeUserRole", "parameters": [ - { - "type": "integer", - "format": "int64", - "name": "user_id", - "in": "path", - "required": true - }, { "type": "string", "name": "roleUID", @@ -546,6 +539,13 @@ "description": "A flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to remove assignment.", "name": "global", "in": "query" + }, + { + "type": "integer", + "format": "int64", + "name": "user_id", + "in": "path", + "required": true } ], "responses": { @@ -5790,6 +5790,262 @@ } } }, + "/query-history": { + "get": { + "description": "Returns a list of queries in the query history that matches the search criteria.\nQuery history search supports pagination. Use the `limit` parameter to control the maximum number of queries returned; the default limit is 100.\nYou can also use the `page` query parameter to fetch queries from any page other than the first one.", + "tags": ["query_history"], + "summary": "Query history search.", + "operationId": "searchQueries", + "parameters": [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "List of data source UIDs to search for", + "name": "datasourceUid", + "in": "query" + }, + { + "type": "string", + "description": "Text inside query or comments that is searched for", + "name": "searchString", + "in": "query" + }, + { + "type": "boolean", + "description": "Flag indicating if only starred queries should be returned", + "name": "onlyStarred", + "in": "query" + }, + { + "enum": ["time-desc", "time-asc"], + "type": "string", + "default": "time-desc", + "description": "Sort method", + "name": "sort", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size.", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "Limit the number of returned results", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "From range for the query history search", + "name": "from", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "To range for the query history search", + "name": "to", + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistorySearchResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "post": { + "description": "Adds new query to query history.", + "tags": ["query_history"], + "summary": "Add query to query history.", + "operationId": "createQuery", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateQueryInQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/migrate": { + "post": { + "description": "Adds multiple queries to query history.", + "tags": ["query_history"], + "summary": "Migrate queries to query history.", + "operationId": "migrateQueries", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/MigrateQueriesToQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryMigrationResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/star/{query_history_uid}": { + "post": { + "description": "Adds star to query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Add star to query in query history.", + "operationId": "starQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "delete": { + "description": "Removes star from query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Remove star to query in query history.", + "operationId": "unstarQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/{query_history_uid}": { + "delete": { + "description": "Deletes an existing query in query history as specified by the UID. This operation cannot be reverted.", + "tags": ["query_history"], + "summary": "Delete query in query history.", + "operationId": "deleteQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryDeleteQueryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "patch": { + "description": "Updates comment for query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Update comment for query in query history.", + "operationId": "patchQueryComment", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/PatchQueryCommentInQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, "/recording-rules": { "get": { "tags": ["recording_rules", "enterprise"], @@ -9145,6 +9401,21 @@ } } }, + "CreateQueryInQueryHistoryCommand": { + "description": "CreateQueryInQueryHistoryCommand is the command for adding query history", + "type": "object", + "required": ["queries"], + "properties": { + "datasourceUid": { + "description": "UID of the data source for which are queries stored.", + "type": "string", + "example": "PE1C5CBDA0504A6A3" + }, + "queries": { + "$ref": "#/definitions/Json" + } + } + }, "CreateRoleWithPermissionsCommand": { "type": "object", "properties": { @@ -9584,7 +9855,6 @@ } }, "DashboardVersionDTO": { - "description": "DashboardVersionDTO represents a dashboard version, without the dashboard\nmap.", "type": "object", "properties": { "created": { @@ -9680,7 +9950,7 @@ } }, "DataResponse": { - "description": "A map of RefIDs (unique query identifers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.", + "description": "A map of RefIDs (unique query identifiers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.", "type": "object", "title": "DataResponse contains the results from a DataQuery.", "properties": { @@ -10348,7 +10618,7 @@ "type": "string" }, "pathSeparator": { - "description": "PathSeparator defines the separator pattern to decode a hiearchy. The default separator is '/'.", + "description": "PathSeparator defines the separator pattern to decode a hierarchy. The default separator is '/'.", "type": "string" }, "preferredVisualisationType": { @@ -11583,6 +11853,19 @@ } } }, + "MigrateQueriesToQueryHistoryCommand": { + "description": "MigrateQueriesToQueryHistoryCommand is the command used for migration of old queries into query history", + "type": "object", + "properties": { + "queries": { + "description": "Array of queries to store in query history.", + "type": "array", + "items": { + "$ref": "#/definitions/QueryToMigrate" + } + } + } + }, "MonthRange": { "type": "object", "title": "A MonthRange is an inclusive range between [1, 12] where 1 = January.", @@ -12162,6 +12445,16 @@ } } }, + "PatchQueryCommentInQueryHistoryCommand": { + "description": "PatchQueryCommentInQueryHistoryCommand is the command for updating comment for query in query history", + "type": "object", + "properties": { + "comment": { + "description": "Updated comment", + "type": "string" + } + } + }, "PauseAlertCommand": { "type": "object", "properties": { @@ -12684,6 +12977,63 @@ } } }, + "QueryHistoryDTO": { + "type": "object", + "properties": { + "comment": { + "type": "string" + }, + "createdAt": { + "type": "integer", + "format": "int64" + }, + "createdBy": { + "type": "integer", + "format": "int64" + }, + "datasourceUid": { + "type": "string" + }, + "queries": { + "$ref": "#/definitions/Json" + }, + "starred": { + "type": "boolean" + }, + "uid": { + "type": "string" + } + } + }, + "QueryHistoryDeleteQueryResponse": { + "description": "QueryHistoryDeleteQueryResponse is the response struct for deleting a query from query history", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "message": { + "type": "string" + } + } + }, + "QueryHistoryMigrationResponse": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "starredCount": { + "type": "integer", + "format": "int64" + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "QueryHistoryPreference": { "type": "object", "properties": { @@ -12692,6 +13042,46 @@ } } }, + "QueryHistoryResponse": { + "description": "QueryHistoryResponse is a response struct for QueryHistoryDTO", + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/QueryHistoryDTO" + } + } + }, + "QueryHistorySearchResponse": { + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/QueryHistorySearchResult" + } + } + }, + "QueryHistorySearchResult": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int64" + }, + "perPage": { + "type": "integer", + "format": "int64" + }, + "queryHistory": { + "type": "array", + "items": { + "$ref": "#/definitions/QueryHistoryDTO" + } + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "QueryStat": { "description": "The embedded FieldConfig's display name must be set.\nIt corresponds to the QueryResultMetaStat on the frontend (https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L53).", "type": "object", @@ -12777,6 +13167,27 @@ } } }, + "QueryToMigrate": { + "type": "object", + "properties": { + "comment": { + "type": "string" + }, + "createdAt": { + "type": "integer", + "format": "int64" + }, + "datasourceUid": { + "type": "string" + }, + "queries": { + "$ref": "#/definitions/Json" + }, + "starred": { + "type": "boolean" + } + } + }, "Receiver": { "type": "object", "title": "Receiver configuration provides configuration on how to contact a receiver.", @@ -16130,6 +16541,30 @@ "$ref": "#/definitions/Prefs" } }, + "getQueryHistoryDeleteQueryResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryDeleteQueryResponse" + } + }, + "getQueryHistoryMigrationResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryMigrationResponse" + } + }, + "getQueryHistoryResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryResponse" + } + }, + "getQueryHistorySearchResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistorySearchResponse" + } + }, "getQuotaResponse": { "description": "", "schema": { @@ -16576,6 +17011,10 @@ "description": "The identifier (ID) of a library element is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a library element uniquely identifies library elements between multiple Grafana installs. It’s automatically generated unless you specify it during library element creation. The UID provides consistent URLs for accessing library elements and when syncing library elements between multiple Grafana installs.\nThe maximum length of a UID is 40 characters.", "name": "library_elements" }, + { + "description": "The identifier (ID) of a query in query history is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a query history uniquely identifies queries in query history between multiple Grafana installs. It’s automatically generated. The UID provides consistent URLs for accessing queries in query history.", + "name": "query_history" + }, { "description": "The Admin Organizations HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user is called `admin` and has permission to use this API).", "name": "orgs" diff --git a/public/api-spec.json b/public/api-spec.json index 14595a213f9..7024b925234 100644 --- a/public/api-spec.json +++ b/public/api-spec.json @@ -489,13 +489,6 @@ "summary": "Add a user role assignment.", "operationId": "addUserRole", "parameters": [ - { - "type": "integer", - "format": "int64", - "name": "user_id", - "in": "path", - "required": true - }, { "name": "body", "in": "body", @@ -503,6 +496,13 @@ "schema": { "$ref": "#/definitions/AddUserRoleCommand" } + }, + { + "type": "integer", + "format": "int64", + "name": "user_id", + "in": "path", + "required": true } ], "responses": { @@ -528,13 +528,6 @@ "summary": "Remove a user role assignment.", "operationId": "removeUserRole", "parameters": [ - { - "type": "integer", - "format": "int64", - "name": "user_id", - "in": "path", - "required": true - }, { "type": "string", "name": "roleUID", @@ -546,6 +539,13 @@ "description": "A flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to remove assignment.", "name": "global", "in": "query" + }, + { + "type": "integer", + "format": "int64", + "name": "user_id", + "in": "path", + "required": true } ], "responses": { @@ -5790,6 +5790,262 @@ } } }, + "/query-history": { + "get": { + "description": "Returns a list of queries in the query history that matches the search criteria.\nQuery history search supports pagination. Use the `limit` parameter to control the maximum number of queries returned; the default limit is 100.\nYou can also use the `page` query parameter to fetch queries from any page other than the first one.", + "tags": ["query_history"], + "summary": "Query history search.", + "operationId": "searchQueries", + "parameters": [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "List of data source UIDs to search for", + "name": "datasourceUid", + "in": "query" + }, + { + "type": "string", + "description": "Text inside query or comments that is searched for", + "name": "searchString", + "in": "query" + }, + { + "type": "boolean", + "description": "Flag indicating if only starred queries should be returned", + "name": "onlyStarred", + "in": "query" + }, + { + "enum": ["time-desc", "time-asc"], + "type": "string", + "default": "time-desc", + "description": "Sort method", + "name": "sort", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size.", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "Limit the number of returned results", + "name": "limit", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "From range for the query history search", + "name": "from", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "description": "To range for the query history search", + "name": "to", + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistorySearchResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "post": { + "description": "Adds new query to query history.", + "tags": ["query_history"], + "summary": "Add query to query history.", + "operationId": "createQuery", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/CreateQueryInQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/migrate": { + "post": { + "description": "Adds multiple queries to query history.", + "tags": ["query_history"], + "summary": "Migrate queries to query history.", + "operationId": "migrateQueries", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/MigrateQueriesToQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryMigrationResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/star/{query_history_uid}": { + "post": { + "description": "Adds star to query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Add star to query in query history.", + "operationId": "starQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "delete": { + "description": "Removes star from query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Remove star to query in query history.", + "operationId": "unstarQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, + "/query-history/{query_history_uid}": { + "delete": { + "description": "Deletes an existing query in query history as specified by the UID. This operation cannot be reverted.", + "tags": ["query_history"], + "summary": "Delete query in query history.", + "operationId": "deleteQuery", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryDeleteQueryResponse" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + }, + "patch": { + "description": "Updates comment for query in query history as specified by the UID.", + "tags": ["query_history"], + "summary": "Update comment for query in query history.", + "operationId": "patchQueryComment", + "parameters": [ + { + "type": "string", + "name": "query_history_uid", + "in": "path", + "required": true + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/PatchQueryCommentInQueryHistoryCommand" + } + } + ], + "responses": { + "200": { + "$ref": "#/responses/getQueryHistoryResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, "/recording-rules": { "get": { "tags": ["recording_rules", "enterprise"], @@ -8890,6 +9146,21 @@ } } }, + "CreateQueryInQueryHistoryCommand": { + "description": "CreateQueryInQueryHistoryCommand is the command for adding query history", + "type": "object", + "required": ["queries"], + "properties": { + "datasourceUid": { + "description": "UID of the data source for which are queries stored.", + "type": "string", + "example": "PE1C5CBDA0504A6A3" + }, + "queries": { + "$ref": "#/definitions/Json" + } + } + }, "CreateRoleWithPermissionsCommand": { "type": "object", "properties": { @@ -9328,7 +9599,6 @@ } }, "DashboardVersionDTO": { - "description": "DashboardVersionDTO represents a dashboard version, without the dashboard\nmap.", "type": "object", "properties": { "created": { @@ -9424,7 +9694,7 @@ } }, "DataResponse": { - "description": "A map of RefIDs (unique query identifers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.", + "description": "A map of RefIDs (unique query identifiers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.", "type": "object", "title": "DataResponse contains the results from a DataQuery.", "properties": { @@ -9874,7 +10144,7 @@ "type": "string" }, "pathSeparator": { - "description": "PathSeparator defines the separator pattern to decode a hiearchy. The default separator is '/'.", + "description": "PathSeparator defines the separator pattern to decode a hierarchy. The default separator is '/'.", "type": "string" }, "preferredVisualisationType": { @@ -10433,6 +10703,19 @@ } } }, + "MigrateQueriesToQueryHistoryCommand": { + "description": "MigrateQueriesToQueryHistoryCommand is the command used for migration of old queries into query history", + "type": "object", + "properties": { + "queries": { + "description": "Array of queries to store in query history.", + "type": "array", + "items": { + "$ref": "#/definitions/QueryToMigrate" + } + } + } + }, "NavLink": { "type": "object", "properties": { @@ -10696,6 +10979,16 @@ } } }, + "PatchQueryCommentInQueryHistoryCommand": { + "description": "PatchQueryCommentInQueryHistoryCommand is the command for updating comment for query in query history", + "type": "object", + "properties": { + "comment": { + "description": "Updated comment", + "type": "string" + } + } + }, "PauseAlertCommand": { "type": "object", "properties": { @@ -10845,6 +11138,63 @@ } } }, + "QueryHistoryDTO": { + "type": "object", + "properties": { + "comment": { + "type": "string" + }, + "createdAt": { + "type": "integer", + "format": "int64" + }, + "createdBy": { + "type": "integer", + "format": "int64" + }, + "datasourceUid": { + "type": "string" + }, + "queries": { + "$ref": "#/definitions/Json" + }, + "starred": { + "type": "boolean" + }, + "uid": { + "type": "string" + } + } + }, + "QueryHistoryDeleteQueryResponse": { + "description": "QueryHistoryDeleteQueryResponse is the response struct for deleting a query from query history", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "message": { + "type": "string" + } + } + }, + "QueryHistoryMigrationResponse": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "starredCount": { + "type": "integer", + "format": "int64" + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "QueryHistoryPreference": { "type": "object", "properties": { @@ -10853,6 +11203,46 @@ } } }, + "QueryHistoryResponse": { + "description": "QueryHistoryResponse is a response struct for QueryHistoryDTO", + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/QueryHistoryDTO" + } + } + }, + "QueryHistorySearchResponse": { + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/QueryHistorySearchResult" + } + } + }, + "QueryHistorySearchResult": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int64" + }, + "perPage": { + "type": "integer", + "format": "int64" + }, + "queryHistory": { + "type": "array", + "items": { + "$ref": "#/definitions/QueryHistoryDTO" + } + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "QueryStat": { "description": "The embedded FieldConfig's display name must be set.\nIt corresponds to the QueryResultMetaStat on the frontend (https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L53).", "type": "object", @@ -10938,6 +11328,27 @@ } } }, + "QueryToMigrate": { + "type": "object", + "properties": { + "comment": { + "type": "string" + }, + "createdAt": { + "type": "integer", + "format": "int64" + }, + "datasourceUid": { + "type": "string" + }, + "queries": { + "$ref": "#/definitions/Json" + }, + "starred": { + "type": "boolean" + } + } + }, "RecordingRuleJSON": { "description": "RecordingRuleJSON is the external representation of a recording rule", "type": "object", @@ -12757,6 +13168,30 @@ "$ref": "#/definitions/Prefs" } }, + "getQueryHistoryDeleteQueryResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryDeleteQueryResponse" + } + }, + "getQueryHistoryMigrationResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryMigrationResponse" + } + }, + "getQueryHistoryResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistoryResponse" + } + }, + "getQueryHistorySearchResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/QueryHistorySearchResponse" + } + }, "getQuotaResponse": { "description": "", "schema": { @@ -13203,6 +13638,10 @@ "description": "The identifier (ID) of a library element is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a library element uniquely identifies library elements between multiple Grafana installs. It’s automatically generated unless you specify it during library element creation. The UID provides consistent URLs for accessing library elements and when syncing library elements between multiple Grafana installs.\nThe maximum length of a UID is 40 characters.", "name": "library_elements" }, + { + "description": "The identifier (ID) of a query in query history is an auto-incrementing numeric value that is unique per Grafana install.\nThe unique identifier (UID) of a query history uniquely identifies queries in query history between multiple Grafana installs. It’s automatically generated. The UID provides consistent URLs for accessing queries in query history.", + "name": "query_history" + }, { "description": "The Admin Organizations HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user is called `admin` and has permission to use this API).", "name": "orgs"