API client tools

D.Hub REST APIs provide an OpenAPI 3.x specification. Call them with standard HTTP clients or generate a client from the specification. The examples below cover JWT authentication, pagination, and error responses.

Prerequisites

• Obtain a JWT for your D.Hub account as described in API authentication.
• Install the HTTP client you plan to use.

No D.Hub-specific SDK

D.Hub does not provide a dedicated SDK package. Use an HTTP client or generate a client from the OpenAPI specification.

Command-line tools

curl

Send HTTP requests from a terminal and inspect the responses.

# Bearer 토큰으로 목록 조회
curl -H "Authorization: Bearer ${TOKEN}" \
     https://{host}/api/v1/collections

# 항목 생성
curl -X POST https://{host}/api/v1/collections \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-collection"}'

# 파일 업로드(multipart, 파일 필드 이름은 files)
curl -X POST https://{host}/api/v1/datasets/${DATASET_ID}/upload \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "files=@./data.csv"

# jq로 응답 확인
RESP=$(curl -s -H "Authorization: Bearer ${TOKEN}" https://{host}/api/v1/datasets)
echo "$RESP" | jq -r '.[].id'

The API tutorial (Korean) covers the call sequence from token issuance to pipeline execution.

HTTPie

HTTPie uses field-based command-line syntax to compose JSON requests.

# 설치
brew install httpie       # macOS
pip install httpie        # Python 환경

# GET 호출
http GET https://{host}/api/v1/collections \
  Authorization:"Bearer ${TOKEN}"

# POST(필드 = key=value, JSON 요청 본문 생성)
http POST https://{host}/api/v1/collections \
  Authorization:"Bearer ${TOKEN}" \
  name="my-collection" \
  description="HTTPie 예제"

Postman and Insomnia

These graphical HTTP clients let you compose requests and inspect responses. Import the D.Hub OpenAPI specification to generate a collection of endpoints.

1. In Postman, select Import → Link and enter https://{host}/api/v1/openapi.json.
2. Register host and token variables in the Environment.
3. Use an endpoint's Code tab to generate a request example in the language you need.

Use these clients to explore requests and investigate errors. For automation, use command-line tools or language-specific HTTP clients.

Language-specific HTTP clients

Python (requests)

Configure authentication headers on a requests.Session to reuse them across requests.

import requests

class DHubClient:
    def __init__(self, host: str, token: str):
        self.host = host
        self.session = requests.Session()
        self.session.headers["Authorization"] = f"Bearer {token}"

    def get(self, path, **params):
        r = self.session.get(f"{self.host}{path}", params=params)
        r.raise_for_status()
        return r.json()

    def post(self, path, json):
        r = self.session.post(f"{self.host}{path}", json=json)
        r.raise_for_status()
        return r.json()

client = DHubClient("https://{host}", "${TOKEN}")
collection = client.post("/api/v1/collections", {"name": "my-collection"})
print(collection["id"])

This example follows the cursor through all pages.

def list_all(client: DHubClient, path: str, limit: int = 100):
    cursor = None
    while True:
        params = {"limit": limit}
        if cursor:
            params["cursor"] = cursor
        page = client.get(path, **params)
        items = page["items"] if isinstance(page, dict) else page
        yield from items
        cursor = page.get("next_cursor") if isinstance(page, dict) else None
        if not cursor:
            return

for dataset in list_all(client, "/api/v1/datasets"):
    print(dataset["id"], dataset["name"])

JavaScript / Node.js fetch

Run the following fetch example on a Node.js server. External apps first exchange a token for the target service in their BFF, as described in API authentication. Server-to-server BFF calls need neither browser CORS settings nor Manager cookies. Do not put tokens in the external app's browser bundle.

const headers = {
  "Authorization": `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

// GET 목록
const list = await fetch(`https://${host}/api/v1/collections`, { headers })
  .then((r) => r.json());

// POST 생성
const created = await fetch(`https://${host}/api/v1/collections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "my-collection" }),
}).then((r) => r.json());

Generate an OpenAPI client

Use openapi-generator-cli to generate a language-specific client from the D.Hub OpenAPI specification.

# 명세 다운로드(인증이 활성화된 환경에서는 토큰 헤더 필요)
curl -H "Authorization: Bearer ${TOKEN}" \
     -o openapi.json https://{host}/api/v1/openapi.json

# Python 클라이언트 생성
npx @openapitools/openapi-generator-cli generate \
  -i ./openapi.json \
  -g python \
  -o ./dhub2-client-python

# TypeScript Axios 클라이언트 생성
npx @openapitools/openapi-generator-cli generate \
  -i ./openapi.json \
  -g typescript-axios \
  -o ./dhub2-client-ts

Generator	Language	Notes
python	Python 3	Synchronous client based on urllib3
python-pydantic-v1	Python 3	Pydantic v1 models
typescript-axios	TypeScript	Axios-based client
typescript-fetch	TypeScript	fetch-based client
go	Go	Based on net/http
java	Java	Supports Maven project generation

Run npx @openapitools/openapi-generator-cli list for the full generator list.

Error handling

See Error handling (Korean) for the API error-response structure.

• 401 / 403: Refresh the token and check permissions for the request.
• 422: Inspect the detail array for fields that failed validation.
• 500, 502, 503, 504: Choose retry limits and delays appropriate to the operation. The example below uses exponential backoff.

Do not automatically retry operations that may create duplicate results, such as create requests.

import time
import requests

def with_retry(call, max_retries=3):
    retryable_status_codes = {500, 502, 503, 504}

    for attempt in range(max_retries + 1):
        try:
            return call()
        except requests.HTTPError as e:
            if e.response.status_code in retryable_status_codes and attempt < max_retries:
                time.sleep(2 ** attempt)
                continue
            raise

Pagination, sorting, and filtering

• Pagination: Use the limit and cursor query parameters. Pass next_cursor from the response into the next request. See the developer guide overview (Korean) for the response structure.
• Sorting: Use the sort query parameter where the endpoint supports it. Check that endpoint's API reference for descending-order syntax.
• Filtering: See Parameters in the API reference for endpoint-specific query parameters.

Next steps

• API tutorial (Korean) — Practice the call sequence from token issuance to pipeline execution.
• API authentication — Obtain JWTs and service tokens and include them in requests.
• API reference — Check request and response fields for each endpoint.