Skip to content

feat(grafana): add grafana OSS API - #478

Draft
henningpokriefke wants to merge 1 commit into
alchemy-run:mainfrom
henningpokriefke:codex/grafana-sdk
Draft

feat(grafana): add grafana OSS API#478
henningpokriefke wants to merge 1 commit into
alchemy-run:mainfrom
henningpokriefke:codex/grafana-sdk

Conversation

@henningpokriefke

@henningpokriefke henningpokriefke commented Aug 29, 2026

Copy link
Copy Markdown

Adds @distilled.cloud/grafana, an Effect-native SDK for the structured self-hosted Grafana OSS /apis API. The package is generated from pinned Grafana 13.2.0 OpenAPI snapshots and deliberately excludes legacy /api routes, Grafana Cloud APIs, and features that are not present in the OSS image.

109 operations are generated across five API modules:

  • dashboard (dashboard.grafana.app/v2)
  • folder (folder.grafana.app/v1)
  • playlist (playlist.grafana.app/v1)
  • alerting rules (rules.alerting.grafana.app/v0alpha1)
  • alerting notifications (notifications.alerting.grafana.app/v1beta1)

The handwritten runtime layer provides self-hosted Basic/Bearer authentication, /apis URL construction, namespace handling, PATCH media types, pagination, retry-after handling, typed errors, and package exports. scripts/convert.ts contains the Grafana-specific conversion rules; scripts/generate.ts delegates service generation to the shared Distilled generator.

Scope decisions

  • Dashboard, Folder, Playlist, Alert Rules, and Alert Notifications are included.
  • Resource history, status, search, discovery, and access endpoints are generated where exposed by the OSS specs.
  • Grafana Cloud-only APIs, legacy /api endpoints, Secrets Management, and Banners are excluded from this self-hosted OSS package.

Verification

I did around 147 tests against a Grafana container, as temporary tests.
The checks were grouped as follows:

  • Wire and protocol checks: authentication, /apis paths, legacy-route rejection, namespaces, headers, JSON and PATCH bodies, pagination, retry handling, typed 404s, and unknown-error fallback.
  • Core resource flows: Dashboard, Folder, and Playlist create/read/replace/merge-patch/delete, selectors, pagination, history, status, access data, folder relationships, collection deletes, and not-found behavior.
  • Alerting flows: Alert Rule, Recording Rule, Rule Sequence, Receiver, Inhibition Rule, Template Group, Time Interval, and Routing Tree lifecycle operations, status endpoints, search, validation failures, resource-version conflicts, and local webhook delivery.
  • OSS boundary checks: discovery confirms the supported API groups; Secrets and Banners are absent from the OSS 13.2.0 surface and are not exposed as working services.

The container test files and Testcontainers dependency are intentionally not shipped in this PR. The package keeps the reproducible snapshots, conversion pipeline, generated services, and handwritten runtime needed by a future Alchemy Grafana provider.

@henningpokriefke
henningpokriefke marked this pull request as draft August 29, 2026 22:25
@henningpokriefke henningpokriefke changed the title feat(grafana): add generated self-hosted SDK feat(grafana): add grafana OSS API Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant