개발자 가이드

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 Chat은 OpenAI Chat Completions와 호환되는 엔드포인트({knowledge_base}/v1/chat/completions)를 제공합니다. 자세한 내용은 API 인증 — Knowledge Chat을 참고하세요.

---

인증

모든 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는 커서 기반 페이지네이션을 사용합니다.

파라미터	타입	설명
limit	integer	한 번에 가져올 항목 수
cursor	string	다음 페이지를 가리키는 커서(이전 응답의 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"
}

자세한 에러 코드와 해결 방법은 에러 처리를 참고하세요.

---

다음 단계

• API를 처음 사용한다면 → API 튜토리얼
• 파이프라인 코드를 작성한다면 → Python 가이드 또는 SQL 가이드
• 외부 시스템과 연동한다면 → API 인증