본문으로 건너뛰기

개발자 가이드

D.Hub REST API는 플랫폼 기능을 프로그래밍 방식으로 제공합니다. 이 가이드는 API 연동, 파이프라인 코드 작성, 데이터 처리에 필요한 정보를 설명합니다.

이 가이드에서 다루는 내용​

문서설명
아키텍처서비스 구조와 개발자용 기술 스택
API 튜토리얼End-to-End 데이터 파이프라인 구축 실습
API 인증JWT 토큰 발급·갱신, 서비스 토큰
API 클라이언트 도구cURL · HTTPie · Python requests · 자동 SDK 생성
오류 처리HTTP 상태 코드, 오류 응답 구조
Python 코드 참조파이프라인 Python 코드 노드(run 함수)
SQL 참조SQL 코드 노드와 자주 쓰는 함수

API 구성​

D.Hub의 핵심 기능은 단일 REST API(OpenAPI 3.x)로 제공됩니다.

Base URL: https://{host}/api/v1/

리소스 그룹은 다음과 같습니다(전체 엔드포인트는 자동 생성 API 레퍼런스가 권위 있는 목록입니다).

  • /collections — 컬렉션
  • /datasets — 데이터셋 CRUD·테이블 업로드/조회·버전
  • /pipelines — 파이프라인 정의·실행·트레이스
  • /ontology — 온톨로지 엔티티·관계
  • /graph — 그래프 쿼리(/graph/query)와 메타데이터
  • /dashboards — 대시보드
  • /knowledges — 지식 베이스·문서
  • /agents · /connectors · /admin 등
추가 서비스

RAG 채팅과 AI 에이전트 API는 각각 별도 서비스 URL을 사용합니다. RAG 채팅은 OpenAI Chat Completions 호환 엔드포인트({knowledge_base}/v1/chat/completions)를 제공합니다. 인증 방식은 Knowledge Chat API 인증에서 확인합니다.

인증​

모든 API 요청에는 JWT Bearer Token이 필요합니다.

curl -H "Authorization: Bearer {token}" \
     https://{host}/api/v1/datasets

토큰은 로그인 API(POST /api/v1/auth/login)로 발급받고 만료되면 Refresh Token으로 갱신합니다. 자동화에 사용할 토큰 선택 기준은 API 인증에서 확인합니다.

데이터 포맷​

요청​

Content-Type: application/json

대부분의 요청 본문은 JSON입니다. 파일 업로드 엔드포인트(예: /datasets/{id}/upload)는 multipart/form-data를 사용합니다.

응답​

{
  "id": "dataset-001",
  "name": "서울시 교통 데이터",
  "created_at": "2026-03-10T09:00:00Z"
}

날짜/시간 값은 ISO 8601 형식(UTC)으로 반환됩니다.

페이지네이션​

목록 조회 API는 커서 기반 페이지네이션을 사용합니다.

파라미터타입설명
limitinteger한 번에 가져올 항목 수
cursorstring다음 페이지를 가리키는 커서(이전 응답의 next_cursor)
# 첫 페이지
GET /api/v1/datasets?limit=50

# 다음 페이지 (이전 응답의 next_cursor 사용)
GET /api/v1/datasets?limit=50&cursor={next_cursor}

응답에는 다음 페이지 조회에 사용할 next_cursor가 포함되며, 더 이상 항목이 없으면 비어 있습니다.

오류 응답​

오류가 발생하면 HTTP 상태 코드와 함께 JSON 오류 메시지가 반환됩니다.

{
  "detail": "Dataset not found"
}

오류 코드와 해결 방법은 오류 처리에서 확인합니다.

다음 단계​