Plugins: Add deprecation notice for /api/tsdb/query endpoint (#45238)

* add deprecation notice for /api/tsdb/query

* fix linking

* regenerate after gen-go

* add newline

* add API docs for ds/query

* regenerate spec

* pr feedback

* add helpful tip

* make sub heading

* add more data

* update spec

* update wording

* mention both from/to

* add suggestions

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* docs feedback

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

pkg/api/api.go

@@ -401,6 +401,7 @@ func (hs *HTTPServer) registerRoutes() {
 		apiRoute.Get("/search/", routing.Wrap(hs.Search))
 
 		// metrics
+		// Deprecated: use /ds/query API instead.
 		apiRoute.Post("/tsdb/query", authorize(reqSignedIn, ac.EvalPermission(datasources.ActionQuery)), routing.Wrap(hs.QueryMetrics))
 
 		// DataSource w/ expressions

pkg/api/docs/definitions/datasources.go

@@ -200,6 +200,8 @@ import (
 //
 // Query metrics.
 //
+// Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead
+//
 // Queries a data source having backend implementation.
 //
 // Most of Grafana’s builtin data sources have backend implementation.
@@ -207,6 +209,8 @@ import (
 // If you are running Grafana Enterprise and have Fine-grained access control enabled
 // you need to have a permission with action: `datasources:query`.
 //
+// Deprecated: true
+//
 // Responses:
 // 200: queryDatasourceResponse
 // 401: unauthorisedError

pkg/api/dtos/models.go

@@ -63,7 +63,7 @@ type MetricRequest struct {
 	// queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
 	// queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.
 	// required: true
-	// example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasourceId": 86, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ]
+	// example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasource":{ "uid":"PD8C576611E62080A" }, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ]
 	Queries []*simplejson.Json `json:"queries"`
 	// required: false
 	Debug bool `json:"debug"`

pkg/api/metrics.go

@@ -145,6 +145,7 @@ func (hs *HTTPServer) QueryMetricsFromDashboard(c *models.ReqContext) response.R
 // POST /api/tsdb/query
 //nolint: staticcheck // legacydata.DataResponse deprecated
 //nolint: staticcheck // legacydata.DataQueryResult deprecated
+// Deprecated: use QueryMetricsV2 instead.
 func (hs *HTTPServer) QueryMetrics(c *models.ReqContext) response.Response {
 	reqDto := dtos.MetricRequest{}
 	if err := web.Bind(c.Req, &reqDto); err != nil {