Skip to main content
Version: v0.1.0

개발자 가이드

D.Hub는 REST API를 통해 플랫폼의 모든 기능을 프로그래밍 방식으로 활용할 수 있습니다. 이 가이드는 API 연동, 파이프라인 코드 작성, 데이터 처리에 필요한 정보를 제공합니다.

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

문서설명
Python 가이드파이프라인에서 Polars 기반 Python 코드 작성법
SQL 가이드ClickHouse SQL 문법과 유용한 함수
API 인증JWT 토큰 발급, 갱신, 서비스 토큰 생성
에러 처리HTTP 상태 코드, 에러 응답 구조, 트러블슈팅
API 튜토리얼End-to-End 데이터 파이프라인 구축 실습

API 서비스 구성​

D.Hub는 두 가지 독립적인 API 서비스를 제공합니다.

Manager API​

데이터셋, 컬렉션, 파이프라인, 온톨로지 등 플랫폼 핵심 기능을 관리하는 138개 엔드포인트를 제공합니다.

Base URL: {host}/api/v1/

주요 리소스:

  • /datasets — 데이터셋 CRUD 및 버전 관리
  • /collections — 컬렉션 관리
  • /pipelines — 파이프라인 정의 및 실행
  • /tables — 테이블 업로드/다운로드 (CSV)
  • /ontologies — 온톨로지 엔티티 및 관계 관리
  • /batches — 배치 처리 및 체크포인트
  • /dashboards — 대시보드 관리
  • /neo4j — 그래프 데이터베이스 직접 쿼리

Knowledge Builder API​

지식 문서 관리, RAG 검색, AI 챗봇 기능을 제공하는 25개 엔드포인트입니다.

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

주요 리소스:

  • /knowledges — 지식 베이스 CRUD
  • /documents — 문서 업로드 및 관리
  • /search — 하이브리드 검색 (BM25 + 벡터)

Knowledge Chat API​

OpenAI API와 호환되는 챗봇 인터페이스를 제공합니다.

Base URL: {host}/v1/chat/completions
OpenAI 호환

Knowledge Chat API는 OpenAI Chat Completions API와 동일한 요청/응답 형식을 사용합니다. 기존 OpenAI SDK를 그대로 활용할 수 있습니다.

인증​

모든 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

모든 API 요청 본문은 JSON 형식입니다. 파일 업로드 엔드포인트(/tables/upload 등)는 multipart/form-data를 사용합니다.

응답​

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

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

페이지네이션​

목록 조회 API는 page와 page_size 쿼리 파라미터로 페이지네이션을 지원합니다.

파라미터타입기본값설명
pageinteger1조회할 페이지 번호
page_sizeinteger20페이지당 항목 수
GET /api/v1/datasets?page=2&page_size=50

응답에는 전체 항목 수와 현재 페이지 정보가 포함됩니다.

에러 응답​

API 에러 발생 시 HTTP 상태 코드와 함께 JSON 형식의 에러 메시지가 반환됩니다.

{
  "detail": "Dataset not found"
}

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

다음 단계​