Grafana API Clients

@grafana/api-clients is currently in ALPHA.

This package provides reusable clients for Grafana APIs. The implementation is in ALPHA and the package is now published on npm as @grafana/api-clients.

The clients are auto-generated RTK Query API clients for Grafana's App Platform APIs.

Installation

yarn add @grafana/api-clients

TypeScript configuration

This package uses subpath exports, which require moduleResolution to be set to "bundler" in your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

If you use ts-node, add the following to your tsconfig.json:

{
  "ts-node": {
    "compilerOptions": {
      "module": "es2020",
      "moduleResolution": "Bundler"
    }
  }
}

Usage

Each API client is available as a separate subpath export, scoped by group and version:

import { generatedAPI } from '@grafana/api-clients/rtkq/<group>/<version>';

For example, to use the dashboard API or a hook:

import { generatedAPI, useListDashboardsQuery } from '@grafana/api-clients/rtkq/dashboard/v0alpha1';

Adding RTKQ middleware to your Redux store

If you're using this package in the context of the Grafana application, the middleware is already added for all API clients, so you don't need to add it manually. If you're using this package for something else, outside of the core Grafana UI, you can add the middleware and reducers to your Redux store by importing the allMiddleware and allReducers exports.

import { allMiddleware, allReducers } from '@grafana/api-clients/rtkq';

const store = configureStore({
  reducer: {
    ...allReducers,
  },
  middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(...allMiddleware),
});

Development (within grafana/grafana)

Generating RTK Query API Clients

This guide explains how to generate API clients for Grafana APIs using this package.

1. Generate an OpenAPI snapshot

First, check if the group and the version are already present in openapi_test.go. If so, move on to the next step. If you need to add a new block, you can check for the right group and version in the backend API call that you want to replicate in the frontend.

{
  Group:   "dashboard.grafana.app",
  Version: "v0alpha1",
}

Afterwards, you need to run the TestIntegrationOpenAPIs test with go test ./pkg/tests/apis -run TestIntegrationOpenAPIs. Note that it will fail the first time you run it. On the second run, it will generate the corresponding OpenAPI spec, which you can find in openapi_snapshots.

Note: You don't need to follow these two steps if the group you're working with is already in the openapi_test.go file.

2. Run the API generator script

Run yarn generate:api-client and follow the prompts. See API Client Generator for details.

Updating generated clients

Use this flow when an existing API changes and you need to regenerate the API types, OpenAPI specs, and RTK Query endpoints.

1. Update the source API schema or types.

   • If the API is generated from kinds/, run make gen-cue after changing the CUE definitions.
   • If the API is defined as Go types in an app platform API package (e.g. pkg/apis/<group>/<version>/), update the types and then run ./hack/update-codegen.sh to regenerate zz_generated.deepcopy.go and zz_generated.openapi.go. This is also included in make gen-apps.

2. Check that openapi_test.go includes the target Group and Version.

   • Add a new entry to the groups list if the API group/version is not present.
   • Add any required feature toggle to EnableFeatureToggles so the API is registered during the test.

3. Generate or update the OpenAPI snapshot:

   bashCopy

   go test ./pkg/tests/apis -run TestIntegrationOpenAPIs
   

   This updates files in openapi_snapshots.

4. Regenerate the processed OpenAPI specs and RTK Query endpoints:

   bashCopy

   yarn generate-apis
   

   This processes snapshots into packages/grafana-openapi/src/apis/*.json and regenerates endpoints.gen.ts files under packages/grafana-api-clients/src/clients/rtkq/.

5. Review the generated diff. A typical update includes:

   • Source API type or schema files.
   • pkg/tests/apis/openapi_snapshots/<group>.grafana.app-<version>.json.
   • packages/grafana-openapi/src/apis/<group>.grafana.app-<version>.json.
   • packages/grafana-api-clients/src/clients/rtkq/<group>/<version>/endpoints.gen.ts.

You can also run yarn generate:api-client and select an existing API group/version. The generator will offer to update the existing client by running the endpoint generation step without modifying the client config or Redux wiring.

Troubleshooting generated client updates

• If the OpenAPI snapshot is missing, check the Group, Version, and feature toggles in pkg/tests/apis/openapi_test.go.
• If the processed spec in packages/grafana-openapi/src/apis/ does not change, verify that TestIntegrationOpenAPIs changed the snapshot first.
• If endpoints.gen.ts does not change, verify that packages/grafana-api-clients/src/scripts/generate-rtk-apis.ts includes the API group/version.