개요 버전 관리 정책 하위 호환성 V1에서 V2로의 마이그레이션 엔드포인트 변경 사항 응답 형식 업데이트 사용 중단 타임라인 주요 변경 사항 단계별 마이그레이션 지원 및 리소스

API 문서

API 마이그레이션 가이드 — 버전 간 업그레이드

API 버전 업그레이드를 원활하게 계획하고 실행하세요. 주요 변경 사항, 사용 중단 타임라인, Smart Money API 버전 간 마이그레이션을 위한 모범 사례를 이해하세요.

2026년 3월 21일 게시 • 16분 읽기 • 고급

마이그레이션 개요

Smart Money API는 정기적인 업데이트로 활발히 개발 중입니다. 이 가이드는 버전 관리, 주요 변경 사항, 다운타임 없이 통합을 마이그레이션하는 방법을 다룹니다.

마이그레이션 핵심 원칙:

시맨틱 버저닝 — MAJOR.MINOR.PATCH 형식 엄격 준수
장기 지원 — 이전 주요 버전 24개월 이상 지원
사용 중단 경고 — 모든 주요 변경 사항에 대해 6개월 사전 공지
병행 버전 — 마이그레이션 기간 동안 v1과 v2 동시 실행
자동화 테스트 — 테스트 스위트 호환성 도구 제공

현재 상태: v1(현재), v2(베타, 2026년 2분기 일반 제공). v1은 2028년 1분기까지 지원됩니다.

버전 관리 정책

시맨틱 버저닝

버전 형식
API 버전: MAJOR.MINOR.PATCH
예시: 2.1.3
MAJOR(2) - 주요 변경 사항, 새로운 아키텍처
MINOR(1) - 하위 호환 기능
PATCH(3) - 버그 수정, 보안 업데이트

버전 출시 주기

단계	기간	특징
알파	2-4주	주요 변경 사항 많음, 테스트 전용
베타	4-8주	대체로 안정적, 커뮤니티 피드백
출시 후보	2-4주	프로덕션 준비 완료, 최종 다듬기
일반 제공	24개월 이상	완전한 프로덕션 지원

30초 안에 API 키 받기

구축할 준비가 되셨나요? 무료 API 키(일일 100회 호출, 카드 불필요)를 받아 실시간 고래, 펀딩 및 온체인 데이터를 가져오세요.

API 키 받기 →

하위 호환성

버전 호환성

주요 버전 내에서는 항상 새로운 마이너/패치 버전으로 안전하게 업그레이드할 수 있습니다:

엔드포인트 URL — 변경되지 않음
필수 필드 — 제거되지 않음(새로운 선택적 필드만 추가)
HTTP 상태 코드 — 기존 시나리오에 대해 유지됨
응답 구조 — 핵심 필드 동일 유지
인증 — 인증 메커니즘 변경 없음

우아한 사용 중단

사용 중단 타임라인
// 1개월차: 사용 중단 공지
// Deprecation 헤더로 기능 표시
Deprecation: version="2.2", sunset="2026-09-01"
// 3-6개월차: 활성 사용 중단 기간
// API는 경고를 반환하지만 여전히 작동
X-Deprecation-Warning: 이 엔드포인트는 2026-09-01에 제거될 예정입니다
// 6개월차: 최종 제거
// 엔드포인트는 410 Gone 반환
HTTP/1.1 410 Gone

V1에서 V2로의 마이그레이션

주요 변경 사항

REST API 재설계 — 더 깔끔한 리소스 엔드포인트
응답 형식 — 일관된 래핑, 향상된 오류 처리
인증 — OAuth 2.0 지원 추가(API 키도 계속 작동)
속도 제한 — 개선된 세분화 및 명확성
웹훅 — 재설계된 이벤트 형식 및 서명

엔드포인트 매핑

v1 엔드포인트	v2 엔드포인트	변경 사항
GET /whales	GET /v2/whales/tracking	재구성됨, 필터링 추가
GET /funding	GET /v2/derivatives/funding-heatmap	거래소 매개변수 필수
GET /positions	GET /v2/derivatives/positions	새로운 집계 옵션

엔드포인트 변경 사항

요청 매개변수 변경 사항

V1 요청
// V1: 펀딩 비율
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2 요청
// V2: 동일한 데이터, 더 명확한 구조
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

응답 형식 업데이트

V1 응답 구조

V1 형식
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

V2 응답 구조

V2 형식
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

주요 차이점: 상태 래퍼 없음, 더 명확한 필드 이름, 표준화된 메타데이터.

사용 중단 타임라인

계획된 사용 중단

기능	발표일	중단일	대체 기능
/v1/whales	2026년 1월	2028년 1월	/v2/whales/tracking
/v1/funding	2026년 1월	2028년 1월	/v2/derivatives/funding-heatmap
API 키 전용 인증	2026년 3월	2027년 3월	OAuth 2.0 (키 계속 사용 가능)
웹훅 v1 형식	2026년 2분기	2027년 2분기	웹훅 v2 형식

주요 변경 사항 상세

제거된 엔드포인트

/v1/stats — /v2/metrics로 대체됨
/v1/historical — 새로운 매개변수와 함께 /v2/historical로 대체됨
/v1/alerts/create — POST /v2/alerts로 대체됨

매개변수 변경 사항

limit — 기본값이 100에서 20으로 변경됨 (명시적으로 지정 필요!)
timeframe — 이제 historical 쿼리에 필수 항목임
sort — 형식이 "field asc"에서 "field:asc"로 변경됨

응답 필드 변경 사항

funding → funding_rate
price → mark_price
vol → volume_quote

단계별 마이그레이션

1단계: 계획 (1-2주차)

사용 중단 예정 기능에 대한 기존 통합 검토
v1 엔드포인트를 v2 대응 항목으로 매핑
코드에 영향을 주는 주요 변경 사항 식별
테스트 전략 및 타임라인 수립

2단계: 개발 (3-4주차)

버전 관리 시스템에 v2 브랜치 생성
모든 API 엔드포인트를 v2 URL로 업데이트
요청/응답 처리 업데이트
샌드박스에 대해 단위 테스트 실행

3단계: 테스트 (5-6주차)

전체 통합 테스트 스위트 실행
오류 시나리오 및 경계 조건 테스트
v2 엔드포인트로 부하 테스트
업데이트된 코드에 대한 보안 감사

4단계: 스테이징 (7주차)

v2 코드를 스테이징 환경에 배포
전체 승인 테스트 실행
관계자로부터 승인 받기
롤백 계획 준비

5단계: 프로덕션 (8주차)

프로덕션에 블루-그린 배포
메트릭 및 오류율 모니터링
지원 문제 발생 시 대기
점진적으로 v1 코드 폐기

지원 및 리소스

사용 가능한 도구

마이그레이션 검증기 — 사용 중단된 사용법에 대한 코드 확인
API 업그레이드 검사기 — v1과 v2 호환성 비교
마이그레이션 체크리스트 — 작업 및 타임라인이 포함된 PDF
코드 예시 — 마이그레이션 전/후 샘플

도움 받기

이메일: [email protected]
문서: changelog-versioning.html 참조
Discord: 커뮤니티 지원 채널
엔터프라이즈: 전담 마이그레이션 엔지니어

지금 마이그레이션 시작하기

포괄적인 마이그레이션 도구, 문서 및 지원으로 API v2로 업그레이드하세요. 다운타임 없는 마이그레이션을 지원합니다.

V2 살펴보기

V1은 2028년 1월까지 지원됩니다. 지금 마이그레이션을 계획하세요.