> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 버전과 호환성

> v1과 v1beta의 차이, 하위 호환성 정책, 변경에 강한 클라이언트 작성법

Platform API는 경로에 버전을 담습니다. 대부분의 엔드포인트는 `v1`이고, 아직 안정화 전인 일부는 `v1beta`입니다.

```
https://platform-api.trychainshift.ai/api/v1/platform/runs
https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains
```

## v1과 v1beta

| 버전       | 의미                         | 호환성          |
| -------- | -------------------------- | ------------ |
| `v1`     | 인터페이스가 확정된 안정 버전           | 하위 호환을 유지합니다 |
| `v1beta` | 인터페이스가 아직 바뀔 수 있는 안정화 전 버전 | 보장하지 않습니다    |

## v1의 하위 호환성

`v1` 경로에서는 기존 클라이언트가 계속 동작하도록 유지합니다. 다음 변경은 호환되는 변경으로 보고 예고 없이 반영합니다.

* 응답에 새 필드 추가
* 선택 요청 파라미터 추가
* 새 엔드포인트 추가
* 모델 ID, 실행 상태, 오류 `code`처럼 값 목록이 정해진 필드에 새 값 추가

하위 호환을 깨는 변경은 `v1` 경로에 적용하지 않습니다. 필요하면 새 버전 경로로 제공합니다. 모든 변경은 [Changelog](/changelog)에 기록됩니다.

## v1beta 사용 시 주의

<Warning>
  `v1beta` 엔드포인트는 안정화 전 단계입니다. 응답 필드, 요청 파라미터, 경로가
  예고 없이 바뀌거나 제거될 수 있습니다.
</Warning>

프로덕션에서 beta 엔드포인트에 의존한다면 다음을 권장합니다.

* 호출부를 한곳에 모아 두세요. 경로나 응답이 바뀔 때 고칠 범위가 줄어듭니다.
* 응답을 그대로 저장하기보다 필요한 값만 추출해 자체 스키마로 저장하세요.
* [Changelog](/changelog)를 구독하세요. RSS를 제공합니다.

beta 엔드포인트가 `v1`으로 승격되면 Changelog에 공지합니다.

## 호출하는 엔드포인트의 버전 확인

요청 경로에 `/v1beta/`가 들어 있으면 beta입니다. 각 [API Reference](/api-reference/overview) 페이지 상단에 실제 경로가 적혀 있으니 거기서 확인하세요.

<Note>
  버전은 리소스 단위로 올라갑니다. 같은 데이터를 다루더라도 답변
  조회(`/v1/platform/answers`)와 인용 출처
  통계(`/v1beta/platform/sources/statistics/domains`)처럼 버전이 다를 수
  있습니다.
</Note>

## 변경에 강한 클라이언트

* **모르는 필드는 무시하세요.** 응답에 새 필드가 추가돼도 파싱이 실패하면 안 됩니다. 알 수 없는 키에서 오류를 내는 엄격한 역직렬화 설정을 끄세요.
* **필드가 항상 있다고 가정하지 마세요.** `include` 파라미터로 요청했는지, 데이터가 있는지에 따라 응답에서 빠질 수 있습니다.
* **모르는 값에 대비하세요.** 모델 ID, 실행 `status`, 오류 `code`는 새 값이 추가될 수 있습니다. 분기문에 기본 처리를 두세요.
* **버전 경로를 상수로 분리하세요.** `/api/v1/platform`을 코드 곳곳에 하드코딩하지 않으면 승격 시 한 곳만 고치면 됩니다.