주요 API versioning 전략은 무엇이며, 버전을 어떻게 deprecate하는가?

Question

IT Interview Practice · Accepted Answer

versioning은 기존 client를 깨뜨리지 않고 **breaking change**로 API를 진화시킬 수 있게 한다. 주류 전략은 셋이며, 여기에 deprecation 절차가 더해진다.

## 세 가지 전략

**1. URI versioning** — 버전이 path에 있다.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
가장 단순하고 잘 보인다. 라우팅·캐싱하기 쉽고 브라우저에서 테스트하기 쉽다. 단점: 엄밀히는 "URI는 리소스를 식별한다"를 위반한다(같은 user가 이제 두 URL을 가진다). 단연 가장 흔한 선택이다(GitHub, 과거의 Stripe).

**2. Custom header versioning** — 버전이 헤더로 이동한다.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
URL을 깔끔하게 유지하지만 브라우저에서는 보이지 않고 캐싱하기 더 어렵다.

**3. Media-type (content negotiation) versioning** — 버전이 `Accept`에 있다.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
가장 "RESTful"하지만(리소스 URL은 안정적이고 representation만 버전이 매겨진다), 소비자에게는 가장 접근하기 어렵다.

## 무엇이 breaking인가

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
오직 breaking change만 새 버전이 필요하다. non-breaking change는 현재 버전에 더한다.

## deprecation 절차

1. 문서와 changelog에 날짜와 함께 **공지(Announce)**한다.
2. client가 프로그램적으로 알아채도록 헤더로 **런타임에 신호(Signal)**한다:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. 옛 버전의 사용을 **모니터링(Monitor)**하고 남은 호출자에게 연락한다.
4. 사용이 거의 0에 가까워진 뒤에만 **Sunset**한다.

## 왜 중요한가

면접관은 당신이 의존하는 client를 깨뜨리지 않고 production에서 API를 키울 수 있는지 — 이론이 아니라 실제 운영 관심사 — 를 보려고 이를 묻는다. 가장 강한 답은 두 가지를 구분한다: 첫째, **대부분의 변경은 non-breaking**이며 버전 bump를 아예 유발해서는 안 된다는 것(추가적 변경은 현재 버전으로 들어가고), versioning은 진짜 breaking change에만 남겨 둔다는 것. 둘째, *전략*보다 *절차*가 더 중요하다는 것 — `Deprecation`/`Sunset` 헤더와 사용 모니터링을 갖춘 명확한 deprecation 일정이 실제로 소비자를 보호한다. URI versioning은 가시성과 도구 지원 덕에 실무에서 이기지만, 트레이드오프를 아는 것(header와 media-type은 URL을 안정적으로 유지하고 더 RESTful하지만 발견 가능성이 떨어진다)은 그저 `/v1/`을 흉내 내는 게 아니라 설계 공간을 이해함을 보여 준다.

세 가지 전략

무엇이 breaking인가

deprecation 절차

왜 중요한가

관련 질문