Grafana의 새 HTTP API 구조

Grafana의 새 HTTP API 구조

Grafana의 /apis HTTP API가 어떻게 구성되어 있는지 설명하는 문서예요. 이 API는 표준화된 구조와 일관된 버전 관리를 따르는 Kubernetes 스타일의 API 계층이에요. 요청 경로, 버전, 네임스페이스, 공통 응답 필드를 이해하면 레거시 /api 엔드포인트에서 마이그레이션하거나 새 API를 다룰 때 훨씬 수월해져요.

경로와 응답 형식, 그룹·버전·네임스페이스·리소스 같은 구성 요소를 하나씩 살펴보면서 API 구조를 익혀 보세요.

출처: 문서

본문

Note

Grafana 12 이상에서 사용할 수 있습니다.

이 문서는 Grafana가 /apis HTTP API를 어떻게 구성하는지 설명해요. 이 API는 표준화된 구조와 일관된 버전 관리를 따르는 Kubernetes 스타일의 API 계층이에요. 레거시 /api 엔드포인트에서 마이그레이션하거나 새 API를 다룰 때, 요청 경로·버전·네임스페이스·공통 응답 필드가 어떻게 동작하는지 이어서 확인해 보세요.

시작하기 전에

시작하기 전에 다음을 준비하세요.

  • Grafana 버전: Grafana 12 이상을 사용하세요.
  • API 접근: Grafana 인스턴스에 HTTP 요청을 보낼 수 있는지 확인하세요.
  • 레거시 API 컨텍스트: 마이그레이션을 계획 중이라면 교체하려는 레거시 /api 엔드포인트를 알고 있어야 해요.

레거시 api 엔드포인트에서 마이그레이션하기

Grafana 13은 개선된 새 API(/apis)를 위해 레거시 API 엔드포인트(/api)를 폐기(deprecate)하기 시작해요. 레거시 API는 현재 비활성화되지 않습니다. 레거시 API의 제거는 향후 주요 릴리스에서 계획되어 있으며, 발생할 수 있는 breaking changes는 서비스 중단을 피하기 위해 사전에 충분히 공지됩니다.

자세한 내용은 새 API로 마이그레이션을 참고하세요.

API 구조

Grafana API는 공통 경로 형식과 공통 응답 형태를 사용해요.

API 경로

모든 Grafana API는 다음 표준화된 형식을 따릅니다.

/apis/<GROUP>/<VERSION>/namespaces/<NAMESPACE>/<RESOURCE>[/<NAME>]

API 그룹, 버전, 네임스페이스, 리소스, 그리고 선택적인 리소스 이름에 해당하는 값을 넣어 사용하세요. 개별 리소스에 대한 get·update·delete 같은 동작에는 마지막 /<NAME> 세그먼트를 사용하고, list·create 같은 컬렉션 동작에는 생략해요.

API 응답 형식

모든 Grafana API 응답은 다음 구조를 따릅니다.

{
  "kind": "<KIND>",
  "apiVersion": "<GROUP>/<VERSION>",
  "metadata": {
    "name": "<NAME>",
    "namespace": "<NAMESPACE>",
    "uid": "db323171-c78a-42fa-be98-16a3d799a779",
    "resourceVersion": "1758777451428472",
    "generation": 10,
    "creationTimestamp": "2026-01-23T22:06:40Z",
    "annotations": {}
  },
  "spec": {
    // resource-specific fields
  }
}

요청하는 리소스가 반환하는 값으로 플레이스홀더를 채워 사용하세요.

구성 요소 이해하기

경로와 응답의 각 부분은 서로 다른 목적을 가지고 있어요.

그룹 (<group>)

그룹은 관련 기능을 논리적인 컬렉션으로 묶어요. 예를 들어 dashboard.grafana.app은 대시보드 관련 작업에 사용됩니다.

버전 (<version>)

Grafana API는 세 가지 안정성 수준을 가진 시맨틱 버저닝(semantic versioning)을 사용해요.

수준 형식 설명 사용 사례 기본 활성화?
Alpha v1alpha1 초기 개발 단계. 불안정하고 버그가 있을 수 있으며 제거될 수 있음 새 기능 테스트용 아니요
Beta v1beta1 알파보다 안정적이지만 여전히 일부 변경이 있을 수 있음 비중요(non-critical) 용도 아니요
GA v1 일반 공급(Generally Available). 하위 호환성을 보장하며 안정적 프로덕션 용도 예

Alpha

Alpha 버전은 기능 플래그(feature flag)로 명시적으로 활성화하지 않는 한 서비스되어서는 안 되며, 완전히 실험적이고 큰 변경이 있을 수 있다고 간주해야 해요. Alpha 버전은 별도의 버전을 추가하지 않고 breaking changes를 겪을 수 있으며, 프로덕션 워크플로에서 의존해서는 안 됩니다. Alpha 버전은 더 안정적인 수준으로 승격되지 않고 완전히 제거될 수도 있어요(예: 새 기능을 위해 alpha로 도입된 실험적 API가 해당 기능이 취소될 경우 완전히 제거될 수 있음).

Beta

Beta 버전은 스키마에 breaking changes를 포함해서는 안 되지만, 처리 로직이나 의미(semantics)에는 변경이 있을 수 있어요. 스키마를 깨는 변경은 새 beta 버전을 게시해야 합니다(예: v1beta1 스키마의 breaking changes를 위해 v1beta2를 게시). Beta 버전은 alpha처럼 실험적으로 간주되지는 않지만, 여전히 기본적으로 비활성화되어 있어야 해요.

GA

GA 버전은 기본적으로 활성화되며 완전히 안정적인 것으로 간주할 수 있어요. 이 API에 가할 수 있는 변경은 버그 수정뿐이고, 다른 변경은 대신 새 버전의 API를 게시해야 해요.

네임스페이스 (<namespace>)

네임스페이스는 Grafana 인스턴스 안에서 리소스를 격리해요. 형식은 배포 유형에 따라 달라집니다.

OSS 및 온프레미스 Grafana

  • 기본 조직: 조직 1에는 default를 사용하세요.
  • 추가 조직: org-<ORG_ID>를 사용하세요.

Grafana Cloud

  • 형식: stacks-<STACK_ID>를 사용하세요.
  • 인스턴스 ID: 여러분의 인스턴스 ID가 STACK_ID예요.

인스턴스 ID는 다음 위치에서 찾을 수 있어요.

  • Grafana Cloud 포털: grafana.com으로 이동해 스택을 열고, Grafana 인스턴스의 Details를 선택하세요.
  • Swagger UI: Grafana Cloud 인스턴스에서 /swagger 페이지를 여세요. 관련 엔드포인트에 네임스페이스가 자동으로 채워집니다.

리소스 (<resource>)

리소스는 상호작용하려는 타입이에요. 흔한 예는 다음과 같습니다.

  • 대시보드: dashboards를 사용하세요.
  • 플레이리스트: playlists를 사용하세요.
  • 폴더: folders를 사용하세요.

Kind (<kind>)

kind는 API 응답에서 리소스 타입을 식별하며, 리소스의 단수 형태에 해당합니다. 예를 들어 dashboards 리소스는 Dashboard라는 kind를 가져요.

이름 (<name>)

<name>은 네임스페이스와 리소스 타입 안에서 특정 리소스 인스턴스를 식별하는 고유 식별자예요. <name>은 metadata.uid 필드와는 다릅니다. URL 경로는 항상 metadata.name을 사용해요.

예를 들어 다음과 같이 정의된 대시보드를 가져온다고 해볼게요.

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "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
  }
}

이때 다음 API 호출을 사용하게 되어요.

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview

메타데이터 (Metadata)

metadata 섹션은 리소스 인스턴스에 대한 정보를 담아요. 이 섹션에는 앞서 설명한 name과 namespace와 함께 다음 필드가 포함됩니다.

UID

대부분의 사용 사례에서 무시할 수 있는 내부 식별자예요. 고유 식별자로는 name 필드를 사용하세요. 이 값은 Grafana UID와 다릅니다.

ResourceVersion

리소스의 일부(메타데이터나 status 포함)가 변경될 때마다 바뀌는 값이에요.

이 필드는 다음 용도로 사용하세요.

  • 변경 감지(Change detection): 리소스가 변경되었는지 추적
  • 낙관적 동시성 제어(Optimistic concurrency control): 리소스의 더 새 버전을 덮어쓰는 것을 방지

Generation

spec이 변경될 때만 증가하는 단조 증가 숫자(monotonically increasing number)예요. metadata나 status에 대한 업데이트는 이 값에 영향을 주지 않아요.

CreationTimestamp

객체가 생성된 시간으로, RFC 3339 UTC 타임스탬프 형식이에요(예: 2026-01-23T22:06:40Z).

Annotations

키-값 쌍의 맵이에요.

흔한 annotation은 다음과 같습니다.

  • grafana.app/createdBy 및 grafana.app/updatedBy: 리소스를 만들었거나 마지막으로 수정한 대상을 식별해요. <USER_TYPE>:<UID> 형식을 사용하며, 예를 들어 user:u000000839처럼 써요.
  • grafana.app/folder: 리소스가 폴더를 지원한다면, 객체가 속한 폴더 UID를 담아요.
  • grafana.app/updatedTimestamp: 마지막 수정 시간을 RFC 3339 UTC 타임스탬프로 저장해요(예: 2026-01-23T05:17:31Z).

Labels

리소스를 정리하고 선택하기 위한 선택적 키-값 쌍의 맵이에요.

Spec

spec 필드는 리소스의 원하는 상태(desired state)를 설명해요. 그 구조는 리소스 타입과 API 버전에 따라 달라집니다. 리소스 spec의 정확한 스키마는 Swagger 또는 OpenAPI 문서를 참고하세요.

관련 리소스

Grafana API를 계속 사용하려면 다음 리소스를 활용하세요.

  • 마이그레이션 가이드: 새 API로 마이그레이션을 참고하세요.
  • HTTP API 레퍼런스: HTTP API 레퍼런스를 참고하세요.
  • Swagger UI: Grafana 인스턴스에서 /swagger 페이지를 열어 엔드포인트 스키마를 확인하고 요청을 시험해 보세요.

더 알아보기 (Learn more)