API 버전 관리 가이드: 외주 개발 후에도 클라이언트를 깨뜨리지 않는 하위 호환성 전략
결론부터 말하면, API 버전 관리는 /v1을 붙일지 말지의 문제가 아니라 기존 앱·관리자·파트너 연동이 계속 동작하도록 변경을 분류하고, 문서화하고, 테스트하고, 폐기하는 운영 정책입니다. 출시 후 기능이 추가될수록 API는 제품의 계약서가 됩니다. 이 계약서가 없으면 작은 필드명 변경 하나가 구버전 모바일 앱 오류, 파트너 주문 누락, 관리자 화면 장애, 웹훅 재처리 실패로 이어질 수 있습니다.
따라서 실무 기준은 단순합니다. 하위 호환 변경은 기존 클라이언트가 수정 없이 계속 성공해야 하고, breaking change는 새 버전·병행 운영·마이그레이션 안내가 필요한 변경입니다. Google의 API 설계 지침도 API를 사용자와의 계약으로 보고, 기존 필드 삭제·이름 변경·타입 변경·의미 변경을 특히 위험한 비호환 변경으로 다룹니다. ([google.aip.dev](https://google.aip.dev/180))
API 버전 정책의 목표는 새 기능을 못 만들게 하는 것이 아닙니다. 새 기능을 추가하되, 누가 언제 어떤 버전에서 영향을 받는지 운영팀이 설명할 수 있게 만드는 것입니다.
왜 서비스 출시 후 API 변경이 운영 리스크가 되는가
초기 MVP에서는 /api/users, /api/orders 정도로 충분해 보입니다. 문제는 서비스가 실제 고객을 만나면서 시작됩니다. 앱은 심사를 거쳐야 하고, 파트너사는 배포 일정을 즉시 맞추지 못하며, 내부 관리자는 월말 정산 중에 화면이 바뀌면 업무가 멈춥니다. AI 자동화나 업무 봇이 붙어 있다면 응답 필드 하나가 바뀌어도 프롬프트 후처리, 스프레드시트 적재, 알림 자동화가 꼬일 수 있습니다.
- 모바일 앱: 사용자가 업데이트하지 않으면 구버전 API 호출이 계속 남습니다.
- B2B·파트너 연동: 상대 회사의 개발·검수·배포 주기가 따로 있습니다.
- 관리자·SaaS 대시보드: 프론트와 백엔드를 함께 배포할 수 있더라도 캐시, 권한, 데이터 형식 변경이 장애를 만들 수 있습니다.
- 웹훅·자동화: 이벤트 payload가 바뀌면 재시도, 중복 처리, 정산 로직에 영향을 줍니다.
- 외주 개발 이후 유지보수: 새 개발사가 기존 의도를 모르면 필드 삭제나 검증 로직 강화가 조용한 breaking change가 됩니다.
하위 호환 변경과 breaking change 구분 기준
가장 먼저 해야 할 일은 변경을 감으로 판단하지 않는 것입니다. 아래 표를 변경 요청 검토 템플릿으로 두면 PM, 백엔드, 프론트, 외주 개발사 간 논쟁을 줄일 수 있습니다.
| 변경 유형 | 판정 | 실무 주의점 |
|---|---|---|
| 응답에 새 필드 추가 | 대체로 하위 호환 | 클라이언트가 알 수 없는 필드를 무시하는지 확인합니다. strict JSON 파서, 자동 생성 타입, 엑셀 적재 스크립트는 실패할 수 있습니다. |
| 기존 필드 삭제 | breaking change | 새 필드를 추가하고 기존 필드는 deprecated 처리 후 사용량이 사라질 때 제거합니다. |
| 필드명 변경 | breaking change | name을 displayName으로 바꾸는 것은 삭제와 추가를 동시에 하는 것과 같습니다. |
| 타입 변경 | breaking change | string에서 number, nullable에서 non-null, 배열에서 객체로 바꾸면 기존 클라이언트 파싱이 깨집니다. |
| 선택 query parameter 추가 | 대체로 하위 호환 | 기본값이 기존 동작과 같아야 합니다. 기본 정렬·필터가 바뀌면 의미 변경입니다. |
| 필수 parameter 추가 | breaking change | 구버전 클라이언트는 해당 값을 보낼 수 없습니다. 우선 선택값으로 추가하고 서버 기본값을 둡니다. |
| 새 enum 값 추가 | 조건부 하위 호환 | 클라이언트 switch 문에 default 처리가 없으면 장애가 납니다. 문서에 unknown 처리 원칙을 넣어야 합니다. |
| 상태 코드·에러 포맷 변경 | 상황에 따라 breaking | 프론트가 특정 에러 코드로 문구·재시도·로그아웃을 처리하면 계약의 일부입니다. |
| 인증 방식·토큰 수명 변경 | 대부분 breaking | 앱 자동 로그인, refresh token, 파트너 서버 배치 작업에 직접 영향을 줍니다. 인증 변경은 별도 마이그레이션이 필요합니다. |
| 리소스 ID 형식 변경 | 대부분 breaking | 외부 시스템이 ID 길이, prefix, 문자셋을 DB 컬럼이나 정규식에 고정했을 수 있습니다. |
Stripe와 GitHub 같은 공개 API 운영 사례도 새 리소스, 선택 파라미터, 응답 필드 추가처럼 additive change를 비교적 안전한 변경으로 분류하지만, 실제 서비스에서는 클라이언트 구현 방식까지 함께 봐야 합니다. ([docs.stripe.com](https://docs.stripe.com/upgrades))
API 변경 요청이 들어왔을 때의 의사결정 흐름
- 누가 쓰는 API인지 확인: 모바일 앱, 웹 프론트, 관리자, 파트너, 자동화 봇, 내부 배치 중 어떤 클라이언트가 호출하는지 확인합니다.
- 기존 요청·응답 계약과 비교: OpenAPI 명세, 샘플 payload, 실제 로그를 기준으로 필드·타입·상태 코드·인증·권한 변경을 비교합니다.
- 하위 호환으로 바꿀 수 있는지 먼저 검토: 삭제 대신 새 필드 추가, 필수값 대신 선택값과 기본값, 동작 변경 대신 새 옵션을 우선 검토합니다.
- 불가피하면 새 버전 설계: v2 엔드포인트, 헤더 버전, 날짜 기반 버전 중 서비스 구조에 맞는 방식을 선택합니다.
- 문서·테스트·모니터링을 함께 배포: 코드만 배포하지 말고 변경 로그, 마이그레이션 가이드, 회귀 테스트, 버전별 호출량 대시보드를 같이 준비합니다.
URI, 헤더, 날짜 기반, GraphQL deprecation 비교
API 버전 표기 방식에는 정답 하나가 없습니다. 중요한 것은 고객이 버전을 명확히 고정할 수 있는지, 게이트웨이·캐시·문서·SDK가 그 방식을 잘 지원하는지, 운영팀이 구버전 사용량을 추적할 수 있는지입니다.
| 방식 | 예시 | 장점 | 주의점 | 적합한 상황 |
|---|---|---|---|---|
| URI 버전 | /api/v1/orders | 가장 직관적이고 라우팅·문서·로그 분석이 쉽습니다. | 버전이 많아지면 라우트가 늘고, 일부 엔드포인트만 바뀌어도 전체가 v2처럼 보일 수 있습니다. | 모바일 앱, 스타트업 SaaS, 외주 개발 인수인계가 필요한 서비스 |
| 헤더 버전 | X-Api-Version: 2026-01-01 | URL을 깨끗하게 유지하고 클라이언트별 버전 고정이 쉽습니다. | 프록시, 캐시, API 문서, 테스트 도구가 헤더를 빠뜨리면 문제가 됩니다. | 파트너 API, SDK 제공 API, 고급 게이트웨이 운영 환경 |
| 날짜 기반 버전 | 2026-01-01 | 변경 시점을 명확히 표현하고 고객별 pinning에 유리합니다. | 버전이 너무 자주 생기면 내부 변환 레이어와 지원 정책이 복잡해집니다. | 결제, 정산, 웹훅, B2B 연동처럼 예측 가능성이 중요한 API |
| Accept media type | application/vnd.service.v1+json | HTTP content negotiation 철학과 맞고 표현 형식 버전에 유리합니다. | 비기술 고객·외주 개발사·테스트 도구에는 이해 난도가 높을 수 있습니다. | 성숙한 API 플랫폼, 다양한 표현 포맷을 제공하는 서비스 |
| GraphQL deprecation | @deprecated | 필드 단위로 점진적 전환을 유도할 수 있습니다. | deprecated는 제거가 아니라 경고입니다. 사용량 추적과 제거 일정이 없으면 오래 남습니다. | GraphQL 스키마를 운영하며 프론트·앱 쿼리를 추적할 수 있는 조직 |
Google AIP는 REST URI의 첫 부분에 주요 버전을 포함하고, 서로 다른 주요 버전이 합리적인 전환 기간 동안 함께 동작해야 한다고 설명합니다. GitHub REST API는 X-GitHub-Api-Version 헤더를 사용하고, Stripe는 Stripe-Version 기반의 날짜형 버전 pinning을 운영합니다. ([google.aip.dev](https://google.aip.dev/185))
REST API 실무 권장 구조
1. 외부 클라이언트가 있다면 처음부터 v1을 계약으로 둔다
서비스가 순수 내부 관리자 화면뿐이라면 URI 버전 없이도 운영할 수 있습니다. 하지만 모바일 앱, 외부 파트너, 고객사 서버, 정부지원사업 MVP 이후 확장 가능성이 있다면 /api/v1처럼 주요 버전을 초기에 두는 편이 안전합니다. 중요한 점은 v1이 기술 이름이 아니라 지원 약속이라는 것입니다.
2. 내부 도메인 모델과 API DTO를 분리한다
많은 장애는 DB 컬럼과 API 응답을 거의 그대로 연결할 때 발생합니다. 내부 테이블 컬럼명을 바꾸거나 정규화 구조를 바꾸는 순간 외부 응답까지 바뀌기 때문입니다. 서버 내부에는 도메인 모델을 두고, 외부로 나가는 값은 UserV1Response, OrderV1Dto처럼 별도 DTO에서 매핑하는 구조가 유지보수에 유리합니다.
3. v2는 코드 전체 복사가 아니라 경계면 분리다
나쁜 v2 전환은 controllers/v1 전체를 복사해 controllers/v2를 만들고 이후 두 코드가 따로 썩는 방식입니다. 좋은 전환은 breaking surface만 분리하고, 인증·권한·핵심 비즈니스 로직은 가능한 공통 서비스 레이어를 사용합니다. 즉, 라우트와 DTO는 버전별로 나누되 내부 정책은 중복하지 않습니다.
4. 인증 변경은 API 버전보다 더 조심스럽게 다룬다
토큰 만료 시간, refresh token 회전, 권한 scope, 세션 무효화 정책은 응답 필드 변경보다 영향이 큽니다. 특히 앱 자동 로그인과 세션 유지가 걸린 서비스라면 API 버전 정책과 인증 정책을 함께 설계해야 합니다. 토큰 구조를 다시 점검해야 한다면 Refresh Token 설계 가이드를 함께 확인하는 것이 좋습니다.
GraphQL을 같이 쓰는 경우: 버전보다 스키마 진화가 먼저
GraphQL은 클라이언트가 필요한 필드를 명시적으로 선택하므로 REST처럼 엔드포인트 전체를 v1, v2로 자주 나누는 방식과 다르게 운영되는 경우가 많습니다. 새 필드는 추가하고, 기존 필드는 바로 제거하지 않고 @deprecated로 대체 필드와 이유를 안내하는 방식이 일반적입니다. 최신 GraphQL 명세에서는 @deprecated가 field, argument, input field, enum value에 사용될 수 있고, introspection으로 deprecated 여부와 reason을 확인할 수 있습니다. ([spec.graphql.org](https://spec.graphql.org/September2025/))
- 필드명 변경: 기존 필드를 유지하고 새 필드를 추가한 뒤 기존 필드에
@deprecated(reason: ...)를 붙입니다. - required argument 폐기: required non-null 인자나 input field는 바로 deprecated 처리할 수 없으므로 먼저 nullable 또는 기본값을 둔 형태로 전환해야 합니다.
- 스키마 제거: 실제 쿼리 사용량을 측정한 뒤 제거합니다. 문서상 deprecated만으로는 안전하지 않습니다.
- REST와 혼합: REST는 URI 또는 헤더 버전, GraphQL은 schema deprecation과 persisted query 사용량 추적으로 나눠 운영하는 편이 명확합니다.
폐기 공지와 마이그레이션: deprecation과 sunset을 구분한다
Deprecation은 지금 당장 동작하지 않는다는 뜻이 아닙니다. 더 이상 권장하지 않으며 앞으로 종료될 수 있다는 신호입니다. Sunset은 특정 시점 이후 해당 리소스나 버전이 응답하지 않을 수 있다는 종료 예고에 가깝습니다. IETF RFC 9745는 Deprecation 응답 헤더로 리소스가 deprecated 되었거나 될 예정임을 알릴 수 있다고 설명하고, RFC 8594는 Sunset 헤더로 리소스가 응답하지 않게 될 예상 시점을 전달하는 방식을 정의합니다. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9745))
Deprecation: @<deprecation_timestamp>
Sunset: Tue, 30 Jun 2026 23:59:59 GMT
Link: <https://docs.example.com/api/migration>; rel=deprecation| 단계 | 서버 조치 | 고객·클라이언트 안내 | 종료 가능 조건 |
|---|---|---|---|
| 1. 공지 | 변경 로그, 문서, OpenAPI deprecated 표기 | 영향 범위, 새 API, 마이그레이션 기한 안내 | 주요 고객·파트너가 공지를 수신함 |
| 2. 병행 운영 | v1과 v2 동시 제공, 로그에 api_version 기록 | 샘플 요청·응답, 필드 매핑표, 테스트 계정 제공 | v2 전환 성공 사례 확보 |
| 3. 경고 강화 | Deprecation/Sunset 헤더, 관리자 알림, 파트너 메일 | 남은 호출량과 미전환 client_id 공유 | 구버전 호출량이 기준 이하로 감소 |
| 4. 신규 사용 차단 | 새 API key는 v1 생성 불가, 신규 앱은 v2만 허용 | 예외 승인 절차 운영 | 기존 고객만 제한적으로 v1 사용 |
| 5. 종료 | 410 Gone 또는 명확한 에러 코드 반환 | 최종 종료 공지와 복구 불가 기준 안내 | 비즈니스·계약상 리스크 검토 완료 |
지원 기간은 업종과 고객 구조에 따라 달라야 합니다. GitHub와 Microsoft Graph처럼 24개월 이상 예고하는 공개 API 사례도 있지만, 작은 내부 관리자 API에 같은 기준을 무조건 적용할 필요는 없습니다. 다만 파트너·정산·결제·공공기관 제출 시스템처럼 변경 비용이 큰 API는 계약서 또는 운영 정책에 폐기 예고 기간을 명시하는 것이 안전합니다. ([docs.github.com](https://docs.github.com/rest/about-the-rest-api/api-versions/))
OpenAPI 문서와 계약 테스트는 선택이 아니라 안전장치
OpenAPI는 사람이 읽는 문서만이 아니라, 클라이언트와 서버가 합의한 요청·응답 구조를 기계가 확인할 수 있게 하는 명세입니다. OpenAPI 명세에는 operation, parameter, header 등에 deprecated 여부를 표기할 수 있어 문서·SDK·검증 도구와 연결하기 좋습니다. ([spec.openapis.org](https://spec.openapis.org/oas/latest.html))
- 명세 원본 관리: Swagger UI 화면만 두지 말고
openapi.yaml또는openapi.json을 Git에 버전 관리합니다. - PR 단계 diff: 기존 명세와 새 명세를 비교해 필드 삭제, required 변경, 타입 변경을 자동 감지합니다.
- 계약 테스트: 주요 앱·파트너가 기대하는 요청과 응답을 테스트로 남깁니다. Pact 같은 소비자 주도 계약 테스트 도구는 consumer가 기대하는 상호작용을 provider에서 검증하는 흐름을 제공합니다. ([docs.pact.io](https://docs.pact.io/?utm_source=openai))
- 샘플 payload 고정: 성공, 인증 실패, 권한 부족, validation error, 빈 목록, pagination, rate limit 응답을 예시로 저장합니다.
- 구버전 앱 회귀 테스트: 앱 최신 버전만 테스트하지 말고, 실제 호출량이 남은 앱 버전의 핵심 플로우를 smoke test에 포함합니다.
외주 개발 후 인수인계에서 반드시 요구할 자료
외주 개발 인수인계에서 API 버전 관리는 자주 빠지는 항목입니다. 하지만 운영 중인 서비스에서는 소스코드보다 변경 기준이 더 중요할 때가 많습니다. 기본 인수인계 범위는 외주개발 인수인계 체크리스트와 함께 보되, API에 대해서는 아래 항목을 별도로 요구해야 합니다.
| 인수인계 항목 | 받아야 할 형태 | 검수 질문 |
|---|---|---|
| API 명세 | OpenAPI 원본 파일, 환경별 base URL, 인증 방식 | Swagger UI가 아니라 원본 파일이 Git에서 관리되는가? |
| 버전 정책 | URI·헤더·날짜 기반 중 선택 이유와 적용 범위 | 어떤 변경이 v2를 필요로 하는지 문서화되어 있는가? |
| 변경 로그 | 날짜, 변경 API, 영향 클라이언트, 마이그레이션 링크 | 구버전 앱이나 파트너가 영향을 받는 변경을 추적할 수 있는가? |
| 테스트 | API 회귀 테스트, 계약 테스트, 샘플 payload | 필드 삭제나 required 변경이 PR에서 잡히는가? |
| 운영 로그 | api_version, client_id, app_version, endpoint, status | 구버전 사용량을 대시보드로 볼 수 있는가? |
| 폐기 계획 | 공지 템플릿, deprecation date, sunset date, 예외 승인 방식 | 종료 전 누구에게 어떤 방식으로 알릴지 정해져 있는가? |
운영 모니터링 체크리스트
API 버전 관리는 배포 후에 완성됩니다. v1을 얼마나 많은 고객이 쓰는지 모르면 v1을 종료할 수 없습니다. v2 오류율이 증가하는지 모르면 마이그레이션을 강행할 수 없습니다. 최소한 다음 지표를 로그와 대시보드에 남겨야 합니다.
- 버전별 요청 수, 오류율, p95 응답 시간
- client_id 또는 partner_id별 구버전 호출량
- 모바일 app_version별 API 호출량과 오류율
- deprecated endpoint 호출 추이
- 인증 실패, 권한 실패, validation error 증가 여부
- 웹훅 재시도·실패·중복 처리 건수
작은 팀이라도 API gateway, application log, tracing에 버전 정보를 남기면 장애 분석 속도가 크게 달라집니다. 관측성 체계를 새로 잡아야 한다면 OpenTelemetry 관측성 가이드처럼 로그·메트릭·트레이스를 함께 설계하는 접근이 도움이 됩니다.
상황별 권장안
| 상황 | 권장 버전 전략 | 핵심 운영 기준 |
|---|---|---|
| 모바일 앱 MVP | /api/v1 URI 버전부터 시작 | 구버전 앱 호출량, 강제 업데이트 가능 여부, 앱 심사 일정을 기준으로 폐기 시점 결정 |
| B2B 파트너 연동 | URI 또는 헤더 버전 + 명시적 계약 문서 | 파트너별 client_id, 변경 공지, 테스트 sandbox, 폐기 예고 기간 필요 |
| 내부 관리자만 있는 서비스 | 무리한 버전 분리보다 명세·회귀 테스트 우선 | 프론트·백엔드 동시 배포가 가능해도 캐시·권한·데이터 포맷 변경은 테스트 |
| REST와 GraphQL 혼합 | REST는 주요 버전, GraphQL은 deprecation과 쿼리 사용량 추적 | 같은 데이터라도 REST DTO와 GraphQL schema의 폐기 정책을 따로 관리 |
| 웹훅·AI 자동화 API | 이벤트 schema version 또는 날짜 기반 pinning | unknown event type, 재시도, idempotency, payload 확장을 기본 전제로 설계 |
| 정부지원사업 MVP 이후 고도화 | 초기에는 단순 v1, 선정 후 파트너·관리자·자동화 확장 대비 | 검수 산출물에 OpenAPI, 테스트, 인수인계 문서를 포함 |
AgentMit이 보는 API 버전 관리의 핵심
AgentMit은 API 버전 관리를 백엔드 라우팅 규칙이 아니라 서비스 운영 구조로 봅니다. BizMit 같은 SaaS, 관리자 대시보드, 업무 자동화, AI 연동 API를 만들 때도 처음부터 모든 것을 복잡하게 만들 필요는 없습니다. 대신 최소한의 버전 정책, OpenAPI 원본, 변경 로그, 회귀 테스트, 운영 로그 필드는 초기에 잡아두는 편이 장기 유지보수 비용을 줄입니다.
특히 외주 개발 이후 팀이 바뀌었거나, 기존 API 명세 없이 기능을 계속 추가하고 있다면 먼저 현재 API를 inventory로 정리해야 합니다. 어떤 endpoint가 실제로 쓰이는지, 어떤 필드가 고객사 자동화에 연결되어 있는지, 어떤 앱 버전이 남아 있는지 확인한 뒤 v2 전환이나 폐기 계획을 세워야 합니다. 구현 도움이 필요하다면 AgentMit은 API 명세 정리, 백엔드 구조 개선, 관리자 화면, 자동화 연동, 운영 문서까지 함께 설계하는 방식으로 지원할 수 있습니다.
FAQ
Q1. API 버전은 처음부터 /v1을 붙여야 하나요?
모바일 앱, 외부 파트너, 공개 API, 여러 개발사가 붙을 가능성이 있다면 처음부터 /api/v1처럼 주요 버전을 노출하는 편이 안전합니다. 내부 관리자 화면처럼 서버와 프론트가 항상 함께 배포된다면 필수는 아니지만, OpenAPI 명세와 변경 로그는 남겨야 합니다.
Q2. 응답 필드를 추가하면 항상 하위 호환인가요?
대체로 하위 호환에 가깝지만 항상 안전한 것은 아닙니다. 클라이언트가 알 수 없는 필드를 무시하지 못하거나, 자동 생성 모델이 strict 모드이거나, 새 enum 값이 기존 분기문을 깨뜨리면 장애가 날 수 있습니다. 필드 추가도 계약 테스트와 샘플 응답 검증을 거쳐야 합니다.
Q3. 모바일 앱 구버전 API는 얼마나 유지해야 하나요?
정답은 서비스마다 다릅니다. 앱 강제 업데이트 가능 여부, 심사 지연, 주요 고객사의 업데이트 주기, 장애 시 매출 영향, 유지보수 비용을 기준으로 정합니다. B2B·파트너 연동은 계약에 폐기 예고 기간을 명시하고, 실제 호출량이 충분히 줄어든 뒤 종료하는 방식이 안전합니다.
Q4. GraphQL도 v1, v2처럼 버전을 나눠야 하나요?
대부분의 GraphQL API는 REST처럼 엔드포인트 버전을 자주 나누기보다 스키마를 점진적으로 확장하고 @deprecated로 이전 필드 사용을 줄입니다. 다만 인증 체계, 권한 모델, 핵심 타입 구조가 크게 바뀌어 같은 스키마에서 유지하기 어렵다면 별도 graph 또는 엔드포인트 분리를 검토할 수 있습니다.
Q5. 외주 개발사에 API 버전 관리로 무엇을 요구해야 하나요?
OpenAPI 원본 파일, 버전 정책 문서, breaking change 체크리스트, 변경 로그, 구버전 병행 운영 방식, 계약 테스트 또는 최소 회귀 테스트, 폐기 공지 템플릿, 운영 로그 필드를 요구해야 합니다. Swagger 화면만 받는 것은 부족합니다.
참고 자료
- Google AIP-180, AIP-185: 하위 호환성과 주요 버전 운영 기준. ([google.aip.dev](https://google.aip.dev/180))
- GitHub REST API Versions, Stripe API Versioning: 헤더·날짜 기반 버전 운영 사례. ([docs.github.com](https://docs.github.com/rest/about-the-rest-api/api-versions/))
- GraphQL Specification September 2025:
@deprecated지시어와 introspection 기준. ([spec.graphql.org](https://spec.graphql.org/September2025/)) - OpenAPI Specification v3.2.0: API 명세와 deprecated 표기 기준. ([spec.openapis.org](https://spec.openapis.org/oas/latest.html))
- RFC 9745, RFC 8594: Deprecation과 Sunset HTTP 헤더. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9745))
- Pact Docs: 소비자 주도 계약 테스트 개념. ([docs.pact.io](https://docs.pact.io/?utm_source=openai))
