API 버전과 변경 정책

XenoCI 러너 API는 경로에 버전을 넣습니다, 지금 버전은 v1이고 모든 엔드포인트는 https://xenoci.com/api/runner/v1 아래에 있습니다, 별도의 버전 헤더는 없습니다

하위 호환 변경

아래 변경은 v1 안에서 알림 없이 할 수 있습니다, 클라이언트는 이 변경에 깨지지 않게 만들어 주세요

• 새 엔드포인트 추가
• 응답에 새 필드 추가, 모르는 필드는 무시하세요
• 요청에 선택 입력 추가
• 새 오류 코드 추가, 모르는 코드는 error.retryable과 HTTP 상태로 처리하세요
• 열거 값 추가 (예: 새 잡 상태, 새 러너 ID), 모르는 값은 일반 값으로 다루세요
• 오류 message 문장 변경, 분기는 error.code로 하세요

깨지는 변경

아래 변경은 새 버전(v2)으로만 합니다

• 엔드포인트나 필드 제거, 이름 변경
• 필드의 타입이나 뜻 변경
• 필수 입력 추가
• 인증 방식 변경

새 버전이 나와도 이전 버전은 일정 기간 함께 동작합니다, 종료 일정은 미리 릴리스 노트와 소유자, 관리자 메일로 알립니다

오류 형식

오류 본문은 항상 error 객체 하나이고 code, message, retryable, retry_after_s, fault, request_id, docs_url, details를 담습니다, v1 안에서 이 필드는 빠지거나 이름이 바뀌지 않고, details 안에 필드가 더해질 수 있습니다

클라이언트 버전

xenocast CLI와 MCP 서버, GitHub Action은 같은 v1 API를 씁니다, 새 기능이 필요할 때만 업데이트하면 되고, 이전 버전도 v1이 동작하는 동안 계속 동작합니다, 바뀐 내용은 릴리스 노트에 날짜순으로 있습니다

다음 단계

• API 레퍼런스 개요
• 오류 코드
• 클라이언트 개요