C# Academy · 강의

API 버전 관리 전략

URL, 헤더 및 쿼리 문자열로 버전을 관리합니다.

API 버전 관리 전략은(는) CoddyKit의 무료 C# Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 C# Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. C# Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

API 버전 관리를 사용하는 이유

클라이언트가 API에 의존하게 되면 해당 계약을 깨뜨릴 수 없습니다. 버전 관리를 사용하면 새 버전에서 호환성이 깨지는 변경 사항을 제공하면서도 기존 클라이언트는 이전 버전을 계속 사용할 수 있습니다.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

URL 경로 버전 관리

가장 눈에 잘 띄는 전략은 경로에 버전을 넣는 것입니다. 모호하지 않고 경로 지정, 탐색, 캐싱이 쉽습니다.

GET /api/v1/products
GET /api/v2/products

쿼리 문자열 버전 관리

버전은 쿼리 매개 변수로 전달됩니다. URL은 안정적으로 유지되며, 매개 변수가 없을 때 최신 버전이나 특정 버전을 기본값으로 사용할 수 있습니다.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

헤더 버전 관리

사용자 지정 요청 헤더에 버전을 담아 URL을 깔끔하게 유지합니다. 단점은 브라우저 주소 표시줄에 보이지 않고 직접 테스트하기가 더 어렵다는 것입니다.

GET /api/products
X-Api-Version: 2.0

미디어 형식 버전 관리

콘텐츠 협상이라고도 합니다. 버전은 Accept 헤더의 미디어 형식에 포함됩니다. REST 원칙에는 가장 충실하지만 발견하기는 가장 어려운 방법입니다.

GET /api/products
Accept: application/json;v=2.0

전략 비교하기

각 전략은 발견하기 쉬운 정도와 URL의 깔끔함을 서로 맞바꿉니다.

URL 경로: 가장 쉽게 발견할 수 있지만 URL이 복잡해집니다.
쿼리 문자열: URL이 안정적이고 기본값을 설정하기 쉽습니다.
헤더: URL은 깔끔하지만 브라우저에서는 보이지 않습니다.
미디어 형식: REST 원칙에는 가장 충실하지만 사용하기가 가장 어렵습니다.

// Many teams pick URL path for public APIs

API의 의미 체계적 버전 관리

API 버전은 대개 주 버전만 사용합니다(v1, v2). 부 버전은 기존 클라이언트가 무시할 수 있는 추가적이고 호환성이 깨지지 않는 변경에 사용하십시오.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

사용 중단 예고

이전 버전을 갑자기 삭제하지 마십시오. 해당 버전을 사용 중단 예정으로 표시하고, 종료 예정일을 알리며, 헤더를 통해 클라이언트에 전달하십시오.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

기본 버전

클라이언트가 버전을 보내지 않을 때 어떻게 처리할지 결정하십시오. 일반적인 선택지는 최신 버전 사용, v1 사용, 요청 거부입니다. 동작을 명확히 정하면 예기치 않은 문제를 피할 수 있습니다.

// Strategy: unversioned request -> treat as v1.0

올바른 대상의 버전 관리

내부 구현 세부 정보가 아니라 계약(경로, 요청 및 응답 형태)에 버전을 적용하십시오. v2 엔드포인트도 v1과 대부분의 비즈니스 논리를 공유할 수 있습니다.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

전략 혼합하기

ASP.NET Core의 버전 관리 라이브러리는 여러 원본에서 동시에 버전을 읽을 수 있으므로 클라이언트가 편리한 방법을 선택할 수 있습니다. 다음으로 이를 구성하겠습니다.

// Accept version from URL OR header OR query

빠른 확인

버전 관리 전략에 대한 이해를 확인해 보십시오.

요약

API 버전 관리 전략을 살펴보았습니다.

URL 경로, 쿼리 문자열, 헤더, 미디어 형식이 있습니다.
각 전략은 발견하기 쉬운 정도와 URL의 깔끔함을 서로 맞바꿉니다.
계약에 버전을 적용하고, 원활하게 사용 중단을 예고하며, 기본 버전을 정의하십시오.

다음 주제: ASP.NET Core에서 Asp.Versioning 구성하기

자주 묻는 질문

“API 버전 관리 전략” 강의는 무료인가요?

네 — “API 버전 관리 전략” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 C# Academy 강의 전체를 잠금 해제할 수 있습니다. C# Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“API 버전 관리 전략”에서 뭘 배우나요?

URL, 헤더 및 쿼리 문자열로 버전을 관리합니다. 브라우저에서 직접 실행하는 실습 코드로 C# Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

C# Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 C# Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“API 버전 관리 전략” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 C# Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 C# Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← C# Academy(으)로 돌아가기