Add resource handler for app plugins
You can add a resource handler to your app backend to extend the Grafana HTTP API with your own app-specific routes. This guide explains why you may want to add resource handlers and some common ways for doing so.
Uses of resource handlers​
An app often integrates with a HTTP service of some kind, e.g. a 3rd party service, to retrieve and send data. For example, this service might have specific authentication and authorization needs or a response format not suitable to return to Grafana and the plugin frontend.
In addition, you might want to secure your resources so that only users with a certain permission can access certain routes.
Resource handlers are also useful for building control panels that allow the user to write back to the app. For example, you could add a resource handler to update the state of an IoT device.
Implement the resource handler interface​
To add a resource handler to your backend plugin, you need to implement the backend.CallResourceHandler
interface.
There are two ways you can implement this in your plugin, using the httpadapter
package or manually implementing it in your plugin.
Using the httpadapter
package​
The httpadapter
package provided by the Grafana Plugin SDK for Go is the recommended way for handling resources. This package provides support for handling resource calls using using the http.Handler
interface and allows responding to HTTP requests in a more Go-agnostic way and makes it easier to support multiple routes and methods (GET, POST etc).
Using http.Handler
allows you to also use Go’s built-in router functionality called ServeMux
or your preferred HTTP router library (for example, gorilla/mux
).
Go 1.22 includes routing enhancement that adds support for method matching and wildcards using the ServeMux
.
In the following example we demonstrate using the httpadapter
package, ServeMux
and http.Handler
to add support for retrieving namespaces (/namespaces
), projects (/projects
) and updating the state of some device (/device
) :
package myplugin
import (
"context"
"net/http"
"github.com/grafana/grafana-plugin-sdk-go/backend"
"github.com/grafana/grafana-plugin-sdk-go/backend/resource/httpadapter"
)
type MyPlugin struct {
resourceHandler backend.CallResourceHandler
}
func New() *MyPlugin {
p := &MyPlugin{}
mux := http.NewServeMux()
mux.HandleFunc("/namespaces", p.handleNamespaces)
mux.HandleFunc("/projects", p.handleProjects)
p.resourceHandler := httpadapter.New(mux)
return p
}
func (p *MyPlugin) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
return p.resourceHandler.CallResource(ctx, req, sender)
}
func (p *MyPlugin) handleNamespaces(rw http.ResponseWriter, req *http.Request) {
rw.Header().Add("Content-Type", "application/json")
_, err := rw.Write([]byte(`{ "namespaces": ["ns-1", "ns-2"] }`))
if err != nil {
return
}
rw.WriteHeader(http.StatusOK)
}
func (p *MyPlugin) handleProjects(rw http.ResponseWriter, req *http.Request) {
rw.Header().Add("Content-Type", "application/json")
_, err := rw.Write([]byte(`{ "projects": ["project-1", "project-2"] }`))
if err != nil {
return
}
rw.WriteHeader(http.StatusOK)
}
Accessing the backend plugin context​
You can use the backend.PluginConfigFromContext function to access backend.PluginContext. This holds contextual information about a plugin request, such as the user performing the request:
func (p *MyPlugin) handleSomeRoute(rw http.ResponseWriter, req *http.Request) {
pCtx := backend.PluginConfigFromContext(req.Context())
bytes, err := json.Marshal(pCtx.User)
if err != nil {
return
}
rw.Header().Add("Content-Type", "application/json")
_, err := rw.Write(bytes)
if err != nil {
return
}
rw.WriteHeader(http.StatusOK)
}
Manually implementing backend.CallResourceHandler
​
Manually implementing the backend.CallResourceHandler
interface might be enough for the basic needs. To support a couple of different routes retrieving data you can use a switch with the req.Path
:
func (p *MyPlugin) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
switch req.Path {
case "namespaces":
return sender.Send(&backend.CallResourceResponse{
Status: http.StatusOK,
Body: []byte(`{ "namespaces": ["ns-1", "ns-2"] }`),
})
case "projects":
return sender.Send(&backend.CallResourceResponse{
Status: http.StatusOK,
Body: []byte(`{ "projects": ["project-1", "project-2"] }`),
})
default:
return sender.Send(&backend.CallResourceResponse{
Status: http.StatusNotFound,
})
}
}
Accessing app resources​
Once implemented you can access the resources using the Grafana HTTP API and from the frontend.
Using the Grafana HTTP API​
You can access the resources through the Grafana HTTP API by using the endpoint, http://<GRAFANA_HOSTNAME>:<PORT>/api/plugins/<PLUGIN_ID>/resources{/<RESOURCE>}
. The PLUGIN_ID
is the plugin identifier that uniquely identifies your app and the RESOURCE
depends on how the resource handler is implemented and what resources (routes) are supported.
With the above example you can access the following resources:
- HTTP GET
http://<GRAFANA_HOSTNAME>:<PORT>/api/plugins/<PLUGIN_ID>/resources/namespaces
- HTTP GET
http://<GRAFANA_HOSTNAME>:<PORT>/api/plugins/<PLUGIN_ID>/resources/projects
From the frontend​
You can access your resources in a compontent using the get
function of the backendSrv
runtime service to send a HTTP GET request to http://<GRAFANA_HOSTNAME>:<PORT>/api/plugins/<PLUGIN_ID>/resources/namespaces
import { getBackendSrv } from '@grafana/runtime';
const namespaces = await getBackendSrv().get(`/api/plugins/<PLUGIN_ID>/resources/namespaces`);
Additional examples​
Some other examples of using resource handlers and the httpadapter
package:
- The app-with-backend example:
- create resource handler and register routes in the backend.
- use backendSrv to call resources.