mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 01:32:06 +08:00
100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/new_api_structure/
|
|
- ../../http_api/new_api_structure/
|
|
canonical: /docs/grafana/latest/developers/http_api/new_api_structure/
|
|
description: ''
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
labels:
|
|
products:
|
|
- enterprise
|
|
- oss
|
|
title: New API Structure
|
|
---
|
|
|
|
# Grafana's New API Structure
|
|
|
|
## Overview
|
|
|
|
Going forward, Grafana's HTTP API will follow a standardized API structure alongside consistent API versioning.
|
|
|
|
## API Path Structure
|
|
|
|
All Grafana APIs follow this standardized format:
|
|
|
|
```
|
|
/apis/<group>/<version>/namespaces/<namespace>/<resource>[/<name>]
|
|
```
|
|
|
|
Where the final `/<name>` segment is used for operations on individual resources (like Get, Update, Delete) and omitted for collection operations (like List, Create).
|
|
|
|
## Understanding the Components
|
|
|
|
### Group (`<group>`)
|
|
|
|
Groups organize related functionality into logical collections. For example `dashboard.grafana.app` will be used for all dashboard-related operations.
|
|
|
|
### Version (`<version>`)
|
|
|
|
These APIs will also uses semantic versioning with three stability levels:
|
|
|
|
| Level | Format | Description | Use Case |
|
|
| ----- | ---------- | --------------------------------------------------------------------------- | ------------------------ |
|
|
| Alpha | `v1alpha1` | Early development stage. Unstable, may contain bugs, and subject to removal | For testing new features |
|
|
| Beta | `v1beta1` | More stable than alpha, but may still have some changes | For early production use |
|
|
| GA | `v1` | Generally Available. Stable with backward compatibility guarantees | For production use |
|
|
|
|
### Namespace (`<namespace>`)
|
|
|
|
Namespaces isolate resources within your Grafana instance. The format varies by deployment type:
|
|
|
|
#### OSS & On-Premise Grafana
|
|
|
|
- Default organization (org 1): `default`
|
|
- Additional organizations: `org-<org_id>`
|
|
|
|
#### Grafana Cloud
|
|
|
|
- Format: `stacks-<stack_id>`
|
|
- Your instance ID is the `stack_id`. You can find this value by either:
|
|
- Going to grafana.com, clicking on your stack, and selecting "Details" on your Grafana instance
|
|
- Accessing the /swagger page in your cloud instance, where the namespace will be automatically populated on the relevant endpoints
|
|
|
|
### Resource (`<resource>`)
|
|
|
|
Represents the core resource you want to interact with, such as:
|
|
|
|
- `dashboards`
|
|
- `playlists`
|
|
- `folders`
|
|
|
|
### Name (<name>)
|
|
|
|
The `<name>` is the unique identifier for a specific instance of a resource within its namespace and resource type. `<name>` is distinct from the metadata.uid field. The URL path will always use the metadata.name.
|
|
|
|
For example, to get a dashboard defined as:
|
|
|
|
```
|
|
{
|
|
"kind": "Dashboard",
|
|
"apiVersion": "dashboard.grafana.app/v1beta1",
|
|
"metadata": {
|
|
"name": "production-overview", // This value IS used in the URL path
|
|
"namespace": "default",
|
|
"uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
|
|
// ... other metadata
|
|
},
|
|
"spec": {
|
|
// ... dashboard spec
|
|
}
|
|
}
|
|
```
|
|
|
|
You would use the following API call:
|
|
|
|
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/production-overview`
|