클라이언트 정책

이 문서는 AX Hub SDK 를 쓰는 쪽이 믿어도 되는 약속을 정한다. SDK 는 AX Hub 백엔드를 코드로 호출하게 해 주는 라이브러리다.

1. 개요

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

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

이 문서는 SDK 를 쓰는 쪽이 믿어도 되는 약속을 정한다. 무엇이 버전이 올라가도 그대로인지, 어떤 변경이 예고 없이 일어날 수 있는지를 밝힌다. 개별 API 의 경로·파라미터·응답 필드는 이 문서가 아니라 SDK 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 값만큼 기다렸다가 최대 2회 다시 시도한다. Retry-After 는 서버가 알려 주는 재시도 대기 시간이다. 429 가 아닌 다른 상태는 자동으로 재시도하지 않는다.

5. Deprecation

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

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

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

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

6. 지원 범위

최소 런타임

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

배포 채널

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

지원 버전

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

7. 보안

토큰 취급

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

진단 정보에 토큰이 필요할 때는 redactedToken() 을 쓴다. 이 함수는 실제 토큰 대신 항상 ***REDACTED*** 를 돌려준다.

취약점 신고

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

8. 클라이언트 책임

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

각 엔드포인트의 자세한 사용법은 SDK API 레퍼런스 에 있다.

9. 지원 채널

10. 개정 이력