5626461b3c
* define initial service and add to wire * update caching service interface * add skipQueryCache header handler and update metrics query function to use it * add caching service as a dependency to query service * working caching impl * propagate cache status to frontend in response * beginning of improvements suggested by Lean - separate caching logic from query logic. * more changes to simplify query function * Decided to revert renaming of function * Remove error status from cache request * add extra documentation * Move query caching duration metric to query package * add a little bit of documentation * wip: convert resource caching * Change return type of query service QueryData to a QueryDataResponse with Headers * update codeowners * change X-Cache value to const * use resource caching in endpoint handlers * write resource headers to response even if it's not a cache hit * fix panic caused by lack of nil check * update unit test * remove NONE header - shouldn't show up in OSS * Convert everything to use the plugin middleware * revert a few more things * clean up unused vars * start reverting resource caching, start to implement in plugin middleware * revert more, fix typo * Update caching interfaces - resource caching now has a separate cache method * continue wiring up new resource caching conventions - still in progress * add more safety to implementation * remove some unused objects * remove some code that I left in by accident * add some comments, fix codeowners, fix duplicate registration * fix source of panic in resource middleware * Update client decorator test to provide an empty response object * create tests for caching middleware * fix unit test * Update pkg/services/caching/service.go Co-authored-by: Arati R. <33031346+suntala@users.noreply.github.com> * improve error message in error log * quick docs update * Remove use of mockery. Update return signature to return an explicit hit/miss bool * create unit test for empty request context * rename caching metrics to make it clear they pertain to caching * Update pkg/services/pluginsintegration/clientmiddleware/caching_middleware.go Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com> * Add clarifying comments to cache skip middleware func * Add comment pointing to the resource cache update call * fix unit tests (missing dependency) * try to fix mystery syntax error * fix a panic * Caching: Introduce feature toggle to caching service refactor (#66323) * introduce new feature toggle * hide calls to new service behind a feature flag * remove licensing flag from toggle (misunderstood what it was for) * fix unit tests * rerun toggle gen --------- Co-authored-by: Arati R. <33031346+suntala@users.noreply.github.com> Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
OpenAPI specifications
Since version 8.4, HTTP API details are specified using OpenAPI v2. Starting from version 9.1, there is also an OpenAPI v3 specification (generated by the v2 one using this script).
OpenAPI annotations
The OpenAPI v2 specification is generated automatically from the annotated Go code using go-swagger which scans the source code for annotation rules. Refer to this getting started guide for getting familiar with the toolkit.
Developers modifying the HTTP API endpoints need to make sure to add the necessary annotations so that their changes are reflected into the generated specifications.
Example of endpoint annotation
The following route defines a PATCH endpoint under the /serviceaccounts/{serviceAccountId} path with tag service_accounts (used for grouping together several routes) and operation ID updateServiceAccount (used for uniquely identifying routes and associate parameters and response with them).
// swagger:route PATCH /serviceaccounts/{serviceAccountId} service_accounts updateServiceAccount
//
// # Update service account
//
// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
// action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)
//
// Responses:
// 200: updateServiceAccountResponse
// 400: badRequestError
// 401: unauthorisedError
// 403: forbiddenError
// 404: notFoundError
// 500: internalServerError
The go-swagger can discover such annotations by scanning any code imported by pkg/server but by convention we place the endpoint annotations above the endpoint definition.
Example of endpoint parameters
The following struct defines the route parameters for the updateServiceAccount endpoint. The route expects:
- a path parameter denoting the service account identifier and
- a body parameter with the new values for the specific service account
// swagger:parameters updateServiceAccount
type UpdateServiceAccountParams struct {
// in:path
ServiceAccountId int64 `json:"serviceAccountId"`
// in:body
Body serviceaccounts.UpdateServiceAccountForm
}
Example of endpoint response
The following struct defines the response for the updateServiceAccount endpoint in case of a successful 200 response.
// swagger:response updateServiceAccountResponse
type UpdateServiceAccountResponse struct {
// in:body
Body struct {
Message string `json:"message"`
ID int64 `json:"id"`
Name string `json:"name"`
ServiceAccount *serviceaccounts.ServiceAccountProfileDTO `json:"serviceaccount"`
}
}
OpenAPI generation
Developers can re-create the OpenAPI v2 and v3 specifications using the following command:
make clean-api-spec && make openapi3-gen
They can observe its output into the public/api-merged.json and public/openapi3.json files.
Finally, they can browser and try out both the OpenAPI v2 and v3 via the Swagger UI editor (served by the grafana server) by navigating to /swagger-ui and /openapi3 respectivally.