SDK

AxHub SDK는 백엔드를 코드로 부르게 해 주는 라이브러리예요. node · go · java · kotlin · python · ruby 여섯 언어로 나오고, 전부 같은 OpenAPI 명세 하나에서 만들어져서 동작이 서로 어긋나지 않아요.
이 페이지에 어떤 operation이 있는지 전부와, 버전이 올라가도 믿어도 되는 약속이 있어요. 설치와 인증은 SDK 설치하기에서 다뤄요.

API 한눈에 보기

앱 개발에 자주 쓰는 개발자 표면 operation 87개를 맥락별로 묶었어요. 각 줄을 누르면 경로 · 파라미터 · 응답까지 나와요.

호출 규칙

여섯 언어가 공통으로 지키는 규칙이에요.

• 모든 operation은 pathParams(경로 값) · query(쿼리 문자열) · body(요청 본문) 세 가지로 불러요.
• 응답 키는 camelCase로 바뀌어요. 예외 — 앱 DB 행 조회의 행 내부 키(사용자가 만든 컬럼명)는 원문 그대로예요.
• 배열 응답은 {"value": [...]}로 감싸서 와요. 예외 — 커넥터 리소스 목록처럼 일부는 { items, total, next_cursor } 페이지 응답을 그대로 줘요.
• 경로의 회사 · 앱 식별자는 UUID만 받아요. slug를 넣으면 400이에요.
• 상세 페이지 표의 node 행이 기준이에요. node는 리소스 모델이라 메서드명이 다르고, 나머지 다섯 언어 이름은 operationId에서 나와요.

버전 · 호환성 정책

1. 개요

AX Hub SDK 는 node, go, java, kotlin, python, ruby 6개 언어로 제공된다. 여섯 SDK 는 이름과 문법만 언어에 맞췄을 뿐, 같은 백엔드를 같은 방식으로 호출한다.

여섯 SDK 는 모두 백엔드 OpenAPI 명세 하나에서 만들어진다. OpenAPI 명세는 API 의 요청·응답 형식을 기계가 읽을 수 있게 적어 둔 규격 문서다. 계약(명세)을 먼저 정하고, 그 계약에서 SDK 코드를 뽑아낸다. 그래서 여섯 언어의 동작이 서로 어긋나지 않는다.

이 문서는 SDK 를 쓰는 쪽이 믿어도 되는 약속을 정한다. 무엇이 버전이 올라가도 그대로인지, 어떤 변경이 예고 없이 일어날 수 있는지를 밝힌다. 개별 API 의 경로·파라미터·응답 필드는 이 문서가 아니라 API 한눈에 보기 에 있다.

이 문서의 변경은 10장 개정 이력에 기록된다.

2. 버전 정책

언어별 독립 버전

각 언어 SDK 는 SemVer 를 독립으로 매긴다. SemVer 는 major.minor.patch 세 자리로 버전을 매기는 규칙이다 (예: 2.4.1). 언어마다 릴리스 시점이 다르므로, 같은 기능이라도 버전 숫자는 언어마다 다를 수 있다. 예를 들어 python SDK 가 1.3.0 일 때 go SDK 는 1.5.0 일 수 있다.

계층형 안정성

무엇이 안정이고 무엇이 아직 바뀔 수 있는지를 두 계층으로 나눈다.

route 표면은 SDK 가 제공하는 API 엔드포인트 전체 목록을 뜻한다.

Tier 1 에 나오는 용어를 짧게 풀면 이렇다. 각 항목이 실제로 어떻게 동작하는지는 4장 안정 계약에서 다룬다.

• camelCase: hasMore 처럼 단어 경계를 대문자로 붙여 쓰는 표기.
• PAT: 개인이 발급받는 API 키(Personal Access Token).
• JWT: 로그인 후 받는 서명된 토큰.
• X-Request-ID: 요청 하나를 가리키는 추적용 ID.
• 429: 요청이 너무 잦다는(rate limit) 뜻의 HTTP 상태 코드.

1.0 의 뜻

적합성 검증 corpus 가 동결되는 시점이 1.0 이다. 적합성 검증(conformance) corpus 는 6개 SDK 가 같은 입력에 같은 동작을 하는지 검사하는 테스트 묶음이다. 이 묶음이 고정되면 Tier 2 항목도 안정 계약으로 들어온다.

0.x 규칙

1.0 이전(0.x)에는 API 목록이 minor 버전에서 바뀔 수 있다. 바뀌면 CHANGELOG 에 무엇이 추가·제거·이름 변경 됐는지 명시한다.

3. 호환성 보증

변경을 두 종류로 나눈다. breaking 은 major 버전을 올려야 하는 변경이다. non-breaking 은 minor·patch 에서 언제든 일어날 수 있는 변경이다.

breaking (major 버전을 올린다)

• 기존 operationId 제거 또는 이름 변경 (1.0 이후). operationId 는 각 API 를 가리키는 고유 이름이다.
• 에러 code 또는 category 의 의미 변경.
• 응답 키 표기 규칙 변경.
• 인증 방식 변경.

non-breaking (언제든 일어난다)

• API 추가.
• 응답 필드 추가.
• 에러 code 추가.
• 에러 message 문구 변경.

클라이언트 의무

non-breaking 변경이 코드를 깨지 않게 하려면, SDK 를 쓰는 쪽이 두 가지를 지켜야 한다.

첫째, 모르는 응답 필드는 무시한다. 응답에 새 필드가 늘어도 그대로 두면 된다. 필드가 늘었다고 오류로 처리하지 않는다.

둘째, 에러 분기는 code 와 category 로만 한다. message 문자열에 의존하지 않는다. message 문구는 예고 없이 바뀐다.

# 나쁜 예 — message 문자열에 의존
if "이미 존재" in e.message:
    ...

# 좋은 예 — code 로 분기
if e.code == "slug_taken":
    ...

4. 안정 계약

이 장의 항목은 믿고 코딩해도 된다. 모두 Tier 1 이라, 바뀌면 major 버전이 올라간다.

에러 객체

에러가 나면 SDK 는 아래 필드를 담은 에러 객체를 준다.

message 는 이 목록에 없다. message 는 안정 계약이 아니다. 3장에서 밝혔듯 분기에 쓰지 않는다.

응답 키 표기

응답 키는 camelCase 로 변환된다. 백엔드가 has_more 로 줘도 SDK 는 hasMore 로 바꿔 준다.

예외가 하나 있다. 이 경우의 키는 변환하지 않고 원문 그대로 둔다.

• 앱 DB 행 조회의 행 내부 키(사용자가 만든 테이블의 컬럼명)는 원문 그대로 둔다. 컬럼명은 사용자 것이라 SDK 가 손대지 않는다.

인증

인증 토큰은 두 종류다. 어느 쪽이든 SDK 가 헤더에 실어 보낸다.

• PAT 는 X-Api-Key 헤더로 보낸다.
• JWT 는 Authorization: Bearer 헤더로 보낸다.

토큰을 만들 때 tokenType 을 반드시 명시한다. tokenType 은 토큰이 PAT 인지 JWT 인지 알려 주는 값이다. SDK 는 토큰 종류를 스스로 추측하지 않는다.

요청 추적

모든 요청에 X-Request-ID 가 자동으로 붙는다. 문의할 때 이 값을 함께 주면 해당 요청을 추적할 수 있다.

재시도

429 응답은 자동으로 재시도한다. 이때 SDK 는 서버가 준 Retry-After 값만큼 기다렸다가 다시 시도하며, 대기 자체에 별도 상한을 두지 않는다. Retry-After 는 서버가 알려 주는 재시도 대기 시간이다. 이외에도 안전(safe/idempotent)한 요청은 일시적(retryable) 오류에서 재시도될 수 있고, 401 은 JWT 갱신 후 한 번 재요청된다.

5. Deprecation

deprecated 는 어떤 기능을 곧 없앨 예정이라고 미리 표시하는 것을 뜻한다.

기능 제거는 major 릴리스에서만 한다. minor·patch 에서는 기능을 빼지 않는다.

제거하기 전에 세 가지를 지킨다.

• CHANGELOG 와 문서에 deprecated 로 표기한다.
• 최소 90일 전에 공지한다.
• 대체 방법을 담은 마이그레이션 노트를 함께 제공한다.

6. 지원 범위

최소 런타임

각 SDK 가 요구하는 최소 실행 환경이다. LTS 는 장기 지원(Long-Term Support) 버전을 뜻한다.

배포 채널

각 SDK 는 언어별 표준 저장소에서 받는다.

지원 버전

최신 major 버전만 지원한다. 이전 major 버전은 지원하지 않는다.

7. 보안

토큰 취급

토큰을 로그나 에러 리포트에 남기지 않는다. 토큰이 새면 계정이 노출된다.

진단 정보에 토큰이 필요할 때는 redactedToken() 을 쓴다. 이 함수는 실제 토큰 대신 항상 ***REDACTED*** 를 돌려준다 (go·java·kotlin·python·ruby 제공 — node 는 아직 미제공이므로 토큰을 직접 로그에 남기지 않도록 주의).

취약점 신고

취약점은 GitHub Private Security Advisory 로만 신고한다. Private Security Advisory 는 비공개로 보안 문제를 알리는 GitHub 창구다. 공개 이슈로 올리지 않는다. 접수 확인은 3영업일 이내에 한다.

8. 클라이언트 책임

대부분의 프로토콜 세부는 SDK 가 알아서 처리한다. 다만 아래 2건은 SDK 가 대신 해 주지 않는다. 호출자가 직접 다뤄야 한다.

각 엔드포인트의 자세한 사용법은 API 한눈에 보기 에 있다.

9. 지원 채널

10. 개정 이력