X API v2와 함께 개발자가 X의 공개 API에서 변경 사항이 언제 예상되는지, 그리고 언제 새 버전으로 마이그레이션해야 하는지 더 잘 파악할 수 있도록 하는 새로운 버전 관리 전략을 도입했습니다.
개발자는 개발 로드맵에 이러한 변경 사항을 적절히 반영할 수 있도록 커뮤니케이션 채널을 통해 X API의 지원 중단, 서비스 종료, 변경 및 추가 사항에 대한 공지를 받게 됩니다. API의 모든 변경 사항은 변경 로그에 기록됩니다.
현재 X API에는 세 가지 버전이 있습니다. 귀하의 사용 사례에 필요한 기능이 아직 v2에 제공되지 않은 경우를 제외하고, 통합을 계획할 때는 X API v2 사용을 강력히 권장합니다.
각 버전에 대한 자세한 내용은 다음 페이지를 참조하세요.
버전 관리 전략
X API의 버전은 엔드포인트 라우트 경로에 선언된 버전 번호로 표시됩니다:
https://api.x.com/2/tweets
우리는 필요 시에만 X API의 메이저 버전을 출시하되, 12개월보다 더 짧은 주기로는 출시하지 않는 것을 목표로 합니다. 메이저 버전은 API에 호환성 중단(breaking change)이 도입될 때 출시됩니다. 새로운 메이저 버전을 출시할 때는 개발자가 새 버전으로 이전할 수 있도록 마이그레이션 가이드를 제공합니다.
호환성 중단 변경은 앱의 기존 기능을 유지하려면 개발자가 코드를 수정해야 함을 의미합니다. 비(非)중단 변경은 기존 기능에 추가되는 형태로, 준비가 되면 최신 버전에 순차 반영되며 새로운 기능을 활용하려는 경우가 아니라면 개발자의 추가 작업이 필요하지 않습니다.
보안 또는 개인정보 보호 등의 사유로 릴리스 주기 중간에 호환성 중단 변경을 적용해야 하는 경우, 해당 변경은 최신 버전에 반영됩니다.
기능 중단을 유발하는 변경 사항
이러한 변경 사항은 개발자가 애플리케이션의 기존 기능을 유지하기 위해 코드를 수정해야 함을 의미합니다.
- 새 필수 매개변수 추가
- 기존 엔드포인트 제거
- 응답의 필드 제거(필수 또는 선택 포함)
- 쿼리 매개변수 제거
- 입력 또는 출력 형식 재구성(예: 최상위 필드를 하위 필드로 만들거나 오류 위치를 인라인으로 변경)
- 기존 입력 매개변수 또는 출력 값의 이름 또는 데이터 타입 변경
- 필드 이름 변경
- 리소스 이름 변경
- 응답 코드 변경
- 오류 유형 변경
- 기존 권한 범위 변경
비호환성 없는 변경 사항
- 새 엔드포인트 추가
- 새 선택적 매개변수 추가
- 새 응답 필드 추가
- 오류 메시지 문구 변경
- 새 스코프 제공
- 필드 ‘널 처리’(완전 삭제 대신 개인정보 보호/보안상의 이유로 값을 null로 변경)
지원 중단 및 폐기
먼저, X API에서 지원 중단과 폐기가 무엇을 의미하는지에 대한 우리의 정의는 다음과 같습니다.
- 지원 중단: 해당 기능은 더 이상 팀에서 지원하지 않습니다. 해당 기능과 관련해 새로운 기능은 제공되지 않으며, 제품에 버그나 문제가 있더라도 이를 수정할 가능성은 매우 낮습니다.
- 폐기: 해당 기능은 더 이상 이용할 수 없습니다.
대부분의 경우 새 버전이 출시되면 이전 버전은 즉시 지원 중단 상태로 표시됩니다. 버전은 일정 기간 동안 지원 중단 상태로 유지되며, 이후 폐기됩니다.
향후 지원 중단 및 폐기에 대한 최신 정보를 확인하려면 최신 소식을 확인하세요.