grafana/grafana

App-platform / Kubernetes-style API

Grafana exposes a Kubernetes-style API alongside the legacy REST API. Resources live under:

/apis/<group>/<version>/[namespaces/<ns>/]<resource>[/<name>]

For example:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards
GET /apis/folder.grafana.app/v1/namespaces/default/folders/my-folder
POST /apis/iam.grafana.app/v0alpha1/namespaces/default/teams

Where <group> is one of:

Group	App	Resources
`dashboard.grafana.app`	`apps/dashboard/`	`dashboards` (multiple versions)
`folder.grafana.app`	`apps/folder/`	`folders`
`alerting.grafana.app`	`apps/alerting/`	rules, contact points, policies
`iam.grafana.app`	`apps/iam/`	users, teams, roles, bindings
`provisioning.grafana.app`	`apps/provisioning/`	repositories, jobs
`playlist.grafana.app`	`apps/playlist/`	playlists
...	...	...

Why Kubernetes-style?

Watch / streams — clients can subscribe to resource changes via long-poll or websocket without writing custom polling.
Versioning — multiple coexisting versions per resource, with conversion between them at the API boundary.
Operators — controllers can reconcile resources without bespoke API plumbing.
Tooling — kubectl-flavored clients, code generators, etc.

Implementation

The apiserver is implemented under pkg/services/apiserver/ and uses the upstream Kubernetes apiserver primitives from apimachinery/ and the pkg/aggregator/ package.

Per-resource handlers come from each app's pkg/apis/<group>/<version>/ folder, generated by make gen-apps.

When a request hits a resource version different from the canonical storage version, the apiserver invokes the app's conversion functions (typically in pkg/migration/) before returning. For dashboards, this is the v1 ↔ v2 transform.

Status vs spec

Resources follow the standard Kubernetes split: a spec (desired state) provided by clients and a status (observed state) updated by controllers. Most current resources only use spec; status is reserved for future operator-driven workflows.

Authentication

Same as the REST API — session cookie, bearer token, etc. The apiserver maps the resolved identity to the namespace it can access. In OSS, namespaces correspond to orgs.

Standard verbs

GET (single, list, watch).
POST (create).
PUT (replace), PATCH (partial update).
DELETE.
OPTIONS (CORS).

Plus subresources for things like /scale, /permissions, /snapshot.