API 개요

Connect Base REST API를 사용하면 SDK 없이도 모든 기능에 직접 접근할 수 있습니다.

Base URL

모든 SDK 호환 엔드포인트는 /v1/public/... 으로 시작합니다. 콘솔/관리용 엔드포인트는 /v1/... 이며 사용자 세션(JWT)이 필요합니다.

인증

Connect Base는 두 가지 인증 헤더를 사용합니다.

1. Public Key (개발자용)

X-Public-Key 헤더에 cb_pk_* 또는 cb_sk_* 키를 전달합니다.

curl -X GET "https://api.connectbase.world/v1/public/tables/tbl_xxx/data" \
  -H "X-Public-Key: cb_pk_your_public_key"

2. App Member JWT (앱 사용자용)

signUpMember / signInMember / oauth.signIn 으로 발급받은 토큰은 Authorization: Bearer ... 헤더에 첨부합니다.

curl -X GET "https://api.connectbase.world/v1/public/app-members/me" \
  -H "Authorization: Bearer eyJhbGciOi..."

💡 일부 엔드포인트(예: /v1/public/app-members/me, /v1/public/app-members/me/custom-data)는 JWT 토큰이 반드시 필요합니다. 그 외 엔드포인트는 Public Key 만으로 호출 가능합니다.

요청 형식

• Content-Type: application/json (POST/PUT/PATCH 시)
• Accept: application/json

curl -X POST "https://api.connectbase.world/v1/public/tables/tbl_xxx/data" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{"data": {"name": "홍길동", "email": "[email protected]"}}'

응답 형식

성공 응답은 데이터 객체를 그대로 반환합니다 (envelope wrapper 없음).

{
  "id": "row_abc123",
  "data": { "name": "홍길동", "email": "[email protected]" },
  "created_at": "2026-04-09T00:00:00Z",
  "updated_at": "2026-04-09T00:00:00Z"
}

목록 조회 시:

{
  "data": [
    { "id": "row_1", "data": { ... }, "created_at": "...", "updated_at": "..." },
    { "id": "row_2", "data": { ... }, "created_at": "...", "updated_at": "..." }
  ],
  "total_count": 42,
  "limit": 20,
  "offset": 0,
  "execution_time_ms": 12
}

📌 목록 응답의 필드명은 data 와 total_count 입니다. limit, offset, execution_time_ms 도 함께 반환됩니다.

에러 응답:

{
  "error": "잘못된 데이터 ID입니다."
}

HTTP 상태 코드(400/401/403/404/409/429/500/504)로 에러 종류를 구분하세요. 대부분의 에러 응답은 위의 {"error": "..."} 단순 형태입니다. Rate limit (429) 응답에는 level / retry_after / message 필드가 추가되며, 일부 신규 엔드포인트(예: push 서비스 단계 에러)는 {"success": false, "error": {"code", "message", ...}} 봉투를 사용합니다. ⚠️ SDK 의 ApiError.message 는 단순 형태의 error 문자열에 맞춰 설계되어 있어, 봉투 형태 응답을 받으면 message 가 [object Object] 가 될 수 있습니다 — 해당 엔드포인트에서는 statusCode 로 분기하거나 직접 응답 본문을 fetch 하세요.

페이지네이션

목록 조회 API는 limit / offset 쿼리 파라미터를 지원합니다.

GET /v1/public/tables/tbl_xxx/data?limit=10&offset=0

Rate Limiting

플랜에 따라 API 호출 횟수가 제한됩니다. 한도를 초과하면 429 응답이 반환됩니다.

{
  "error": "Rate limit exceeded",
  "level": "app",
  "retry_after": "60",
  "message": "Your application has exceeded its rate limit. Please wait before making more requests."
}

📌 retry_after 는 문자열로 된 초 단위 값("30", "60", "120")이며 Retry-After HTTP 헤더에도 동일하게 실려옵니다. level 은 어느 단계의 rate limit 에 걸렸는지 (global / app / table / endpoint) 를 표시합니다.

자세한 내용은 흔한 에러 & 해결책 의 backoff 패턴을 참고하세요.

API 버전

현재 API 버전은 v1입니다. URL 경로에 버전이 포함됩니다.