grafana/pkg/api
2023-11-03 09:25:29 -07:00
..
apierrors Plugins: Move store and plugin dto to pluginsintegration (#74655) 2023-09-11 13:59:24 +02:00
avatar Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
datasource backend/datasources: move datasources models into the datasources service package (#51267) 2022-06-27 12:23:15 -04:00
dtos Dashboards: Remove dummy trim dashboard api (#77249) 2023-11-02 08:35:14 -07:00
frontendlogging Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
pluginproxy IDForwarding: Require that id forwarding is enabled for data source (#77131) 2023-10-27 08:30:33 +02:00
response Errors: Make errors the same in dev as prod (#77366) 2023-10-30 14:06:26 -04:00
routing Chore: Move ReqContext to contexthandler service (#62102) 2023-01-27 08:50:36 +01:00
static API: Extract OpenAPI specification from source code using go-swagger (#40528) 2022-02-08 13:38:43 +01:00
accesscontrol.go Bug fix: add library panel permissions to basic roles (#77144) 2023-10-25 18:44:55 +01:00
admin_encryption.go Config: Add configuration option to define custom user-facing general error message for certain error types (#70023) 2023-06-16 10:46:47 -05:00
admin_provisioning_test.go RBAC: Rewrite provisioning rbac tests (#61752) 2023-01-19 13:49:57 +01:00
admin_provisioning.go Chore: Move ReqContext to contexthandler service (#62102) 2023-01-27 08:50:36 +01:00
admin_test.go Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
admin_users_test.go Errors: Make errors the same in dev as prod (#77366) 2023-10-30 14:06:26 -04:00
admin_users.go Authn: Prevent empty username and email during sync (#76330) 2023-10-11 14:27:43 +02:00
admin.go Auth: Move access control API to SignedInUser interface (#73144) 2023-08-18 11:42:18 +01:00
alerting.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
annotations_test.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
annotations.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
api.go EntityStore: Remove http access (can use apiserver now) (#77602) 2023-11-03 08:14:51 -07:00
apikey.go Chore: Port user services to identity.Requester (#73851) 2023-08-28 10:42:24 +02:00
basic_auth_test.go Macaron: remove custom Request type (#37874) 2021-09-01 11:18:30 +02:00
basic_auth.go Macaron: remove custom Request type (#37874) 2021-09-01 11:18:30 +02:00
common_test.go Teams: Move team API to own service (#76347) 2023-10-12 10:10:54 +02:00
dashboard_permission_test.go authz: Clean up acl endpoints and dashboard guardian (#73746) 2023-08-24 15:37:54 +02:00
dashboard_permission.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
dashboard_snapshot_test.go Authz: fix snapshot tests legacy guardian (#73823) 2023-08-28 09:49:10 +02:00
dashboard_snapshot.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
dashboard_test.go Search: Fix empty folder details for nested folder items (#76504) 2023-10-24 10:04:45 +03:00
dashboard.go Dashboards: Remove dummy trim dashboard api (#77249) 2023-11-02 08:35:14 -07:00
dataproxy.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
datasources_test.go Team LBAC: Fix backend validation (#77612) 2023-11-03 17:02:57 +03:00
datasources.go Team LBAC: Fix backend validation (#77612) 2023-11-03 17:02:57 +03:00
fakes.go Plugins: Add context to StaticRouteResolver and ErrorResolver interfaces (#73121) 2023-08-10 10:32:12 +02:00
featuremgmt_test.go Feature Management: Define HideFromAdminPage and AllowSelfServe configs (#77580) 2023-11-03 15:59:07 +00:00
featuremgmt.go Feature Management: Define HideFromAdminPage and AllowSelfServe configs (#77580) 2023-11-03 15:59:07 +00:00
folder_bench_test.go Chore: Replace mock guardian with the actual one in folder API benchmarks (#76231) 2023-10-10 13:31:55 +03:00
folder_permission_test.go authz: Clean up acl endpoints and dashboard guardian (#73746) 2023-08-24 15:37:54 +02:00
folder_permission.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
folder_test.go Nested folders: Fix folder hierarchy in folder responses (#74516) 2023-09-08 10:43:41 +03:00
folder.go Search: Fix empty folder details for nested folder items (#76504) 2023-10-24 10:04:45 +03:00
frontend_logging_test.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
frontend_logging.go Plugins: Add context to StaticRouteResolver and ErrorResolver interfaces (#73121) 2023-08-10 10:32:12 +02:00
frontend_metrics.go Chore: Move ReqContext to contexthandler service (#62102) 2023-01-27 08:50:36 +01:00
frontendsettings_test.go Plugins: Move store and plugin dto to pluginsintegration (#74655) 2023-09-11 13:59:24 +02:00
frontendsettings.go Chore: Upgrade Go to 1.21.3 (#77304) 2023-11-01 09:17:38 -07:00
grafana_com_proxy.go API: don't re-add /api suffix to grafana.com API URL (#62280) 2023-01-27 10:20:55 +01:00
health_test.go HealthCheck: show enterprise commit (#75242) 2023-09-22 08:17:10 -03:00
health.go Chore: Remove Store interface and use db.DB instead (#60160) 2022-12-13 11:03:36 +01:00
http_server_test.go Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
http_server.go EntityStore: Remove http access (can use apiserver now) (#77602) 2023-11-03 08:14:51 -07:00
index.go Navigation: Split admin into subsections behind navAdminSubsections feature toggle (#76280) 2023-10-11 14:37:36 +01:00
login_oauth_test.go Auth: Remove auth broker flag and clean up login handlers (#73109) 2023-08-10 09:56:04 +02:00
login_oauth.go Auth: Remove unused Authenticator service (#73143) 2023-08-10 11:02:32 +02:00
login_test.go Auth: Use authn.Service for all tests (#72921) 2023-08-09 08:54:52 +02:00
login.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
metrics_test.go Errors: Make errors the same in dev as prod (#77366) 2023-10-30 14:06:26 -04:00
metrics.go Chore: Remove plugincontext.ErrPluginNotFound (#74997) 2023-09-25 13:10:47 +03:00
openapi3.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
org_invite_test.go Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
org_invite.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
org_test.go Access: Fetch fresh permissions for target GlobalOrgID in AuthorizeInOrgMiddleware (#76569) 2023-10-13 21:01:47 +03:00
org_users_test.go Contexthandler: Remove code that is no longer used (#73101) 2023-08-09 15:17:59 +02:00
org_users.go Chore: Replace grafana-authnz-team with identity-access-team as code owners (#77609) 2023-11-03 13:20:39 +01:00
org.go Chore: Port user services to identity.Requester (#73851) 2023-08-28 10:42:24 +02:00
password.go Chore: Remove result fields from login (#65136) 2023-03-28 20:32:21 +02:00
playlist.go Playlist: Implement the entire API with k8s client (#77596) 2023-11-03 09:25:29 -07:00
plugin_dashboards_test.go Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
plugin_dashboards.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
plugin_metrics_test.go Chore: Refactor backend plugin errors (#74928) 2023-09-25 11:56:03 +02:00
plugin_metrics.go Chore: Refactor backend plugin errors (#74928) 2023-09-25 11:56:03 +02:00
plugin_proxy_test.go Plugins: Handle app plugin proxy routes per request (#51835) 2022-08-23 13:05:31 +02:00
plugin_proxy.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
plugin_resource_test.go Errors: Make errors the same in dev as prod (#77366) 2023-10-30 14:06:26 -04:00
plugin_resource.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
plugins_test.go Plugins: Move store and plugin dto to pluginsintegration (#74655) 2023-09-11 13:59:24 +02:00
plugins.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
preferences_test.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
preferences.go Teams: Move team API to own service (#76347) 2023-10-12 10:10:54 +02:00
quota_test.go MESA: Allow using synced permissions (#71377) 2023-07-12 13:28:04 +03:00
quota.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
README.md Swagger: Type postDashboardResponse.id as int instead of string (#76749) 2023-10-19 09:16:53 +02:00
render.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
search.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
short_url_test.go Chore: Fix goimports grouping in pkg/api (#62419) 2023-01-30 08:18:26 +00:00
short_url.go Auth: Unfurl OrgID in pkg/api to allow using identity.Requester interface (#76108) 2023-10-06 11:34:36 +02:00
signup.go Identity: Unfurl UserID and Email in pkg/api to user identity.Requester (#76112) 2023-10-09 16:07:28 +02:00
swagger_responses.go PublicDashboards: Add swagger documentation (#75318) 2023-10-30 10:32:07 -03:00
swagger_tags.json Browse Dashboards: Update docs to remove reference to General folder (#74528) 2023-09-08 03:57:16 +01:00
swagger.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
user_test.go Chore: use any rather than interface{} (#74066) 2023-08-30 18:46:47 +03:00
user_token_test.go AuthToken: client token rotation fix (#65709) 2023-03-31 16:44:08 +02:00
user_token.go Chore: Port user services to identity.Requester (#73851) 2023-08-28 10:42:24 +02:00
user.go User: remove empty email / username check from update in service (#77347) 2023-10-30 10:44:26 +01:00
utils.go authz: Clean up acl endpoints and dashboard guardian (#73746) 2023-08-24 15:37:54 +02:00

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 swagger-clean && 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 respectively.