# 버전 관리 및 폐기

> Kanorio의 API 버전 관리 방식, 호환성이 깨지는 변경 사항의 정의, 그리고 기능 제거 전 폐기 알림 절차에 대해 설명합니다.

> Markdown version of https://kanorio.com/ko/developers/basics/versioning. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/versioning.md

세 가지 API 모두 URL에서 `/api/v1`과 같이 버전 관리가 이루어집니다. 호환 가능한 변경 사항은 새로운 버전을 기다리지 않고 지속적으로 배포됩니다. 호환성이 깨지는 변경 사항은 이 페이지의 절차를 따릅니다. 현재 API는 **beta** 단계에 있으며, 구조는 여전히 변경될 수 있고 모든 변경 사항은 [변경 이력](https://kanorio.com/en/developers/changelog)에 먼저 공지됩니다.

## 호환 가능한 변경 사항

이러한 변경 사항은 언제든지 배포될 수 있으므로, 이를 수용할 수 있는 클라이언트를 작성하십시오.

- 새로운 엔드포인트, 작업, MCP 도구 및 Webhook 이벤트 추가
- 새로운 선택적 요청 필드 및 쿼리 매개변수 추가
- 새로운 응답 필드 추가 (알 수 없는 필드는 무시하십시오)
- 새로운 오류 코드 추가 ([오류](https://kanorio.com/ko/developers/basics/errors)에 설명된 대로 HTTP 상태를 기준으로 알 수 없는 코드를 처리하십시오)
- 새로운 권한 추가 및 더 많은 값을 허용하는 완화된 유효성 검사

## 호환성이 깨지는 변경 사항

이러한 변경 사항은 예고 없이 배포되지 않습니다.

- 엔드포인트, 작업, 도구 또는 필드의 제거 또는 이름 변경
- 필드의 유형이나 의미 변경, 또는 선택적 필드를 필수 필드로 변경
- 오류 코드 또는 해당 HTTP 상태 변경
- 유효성 검사 강화 또는 작업에 필요한 권한 변경

안정적인 작업에서 호환성이 깨지는 변경 사항은 폐기 절차를 거치며, 새로운 URL 버전이 도입되어도 이전 버전은 최소 6개월 동안 유지됩니다. 현재 단계에서 호환성이 깨지는 변경 사항은 배포 당일 변경 이력에 나열됩니다.

## 폐기 알림 수신 방법

작업이 폐기되면 모든 채널을 통해 즉시 알림이 제공됩니다.

| 위치 | 표시 내용 |
|---|---|
| 응답 헤더 | `Deprecation`(폐기 날짜), `Sunset`(삭제 날짜), 그리고 본 정책 및 대체 항목으로 연결되는 `Link` 헤더 |
| OpenAPI | 작업에 표시된 `deprecated: true`, `x-kanorio-sunset`, `x-kanorio-replaced-by` |
| MCP | 도구 설명 시작 부분에 `[Deprecated, removed after …; use …]` 문구 표시 |
| API 참조 | 삭제 날짜와 대체 항목이 포함된 폐기 배지 |
| CLI | stderr에 경고 메시지 표시 |
| 이메일 | 최근 30일 이내에 해당 작업을 호출한 토큰 소유자에게 삭제 전 알림 발송 |

```http
Deprecation: @1788134400
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"
```

작업은 폐기 예정일(sunset date)이 지난 후에만 제거됩니다.

## 릴리스 단계

각 작업 및 제품에는 릴리스 단계가 있습니다. [릴리스 단계](https://kanorio.com/ko/developers/basics/release-phases)를 참조하십시오.

## SDK, Elements 및 MCP 버전

- `@kanorio/sdk` 및 `@kanorio/elements`는 시맨틱 버전을 따릅니다. 봇 보호, 크롤러 차단 목록, 리디렉션과 같이 자주 변경되는 규칙은 API를 통해 제공되므로 배포된 프론트엔드는 업그레이드 없이 이를 반영합니다.
- MCP 서버는 `serverInfo` 및 레지스트리 항목에 시맨틱 버전을 게시합니다. 메이저 버전이 변경되면 기존 호출의 동작이 달라질 수 있습니다. 변경될 때마다 변경 이력에 해당 버전이 명시됩니다.