출처: https://qiita.com/gushwell/items/663538393baef926c4c4 

소개

웹 API를 버전 업할 때 호환되지 않는 API로 변경하려는 경우가 나온다.

예를 들면

GET /api/products/

라는 API가 있다고 가정한다. 현재 실행중인 클라이언트 측에 영향을 주지 않으려면,

GET /api/productsV2/

등 다른 이름으로 하는 것이 빠르지만, 대량의 API가 있는 앱이라면 유지보수가 번잡해져서 그다지 좋은 방법이라고는 할 수 없다.

처음부터 버전 관리를 의식한 설계를 해 두는 것이 뭔가 편리한다.

GET /api/v1/products/

GET /api/v2/products/

같이 하는 것이 일반적인 것 같다.

ASP.NET Core Web API에서도 버전 관리를 쉽게 수행할 수 있는 방법이 제공되므로 여기에서는 간략하게 설명한다.

※ 여기에서는 .NET 6에서의 예를 나타낸다.

패키지 설치

Microsoft.AspNetCore.Mvc.Versioning 을 Nuget 패키지 관리자를 사용하여 설치한다.

  1. 솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리(N)...를 선택한다.
  2. 찾아보기 탭을 클릭하고 검색 입력란에 Microsoft.AspNetCore.Mvc.Versioning을 입력한다.
  3. 검색 결과에 Microsoft.AspNetCore.Mvc.Versioning가 표시되므로 이를 선택한다.
  4. 오른쪽 창에 설치 버튼이 표시되므로 설치 버튼을 클릭한다.
  5. 변경 미리보기 대화상자에서 확인 버튼을 클릭한다.
  6. 라이센스 동의 대화 상자에서 I Accept 버튼을 클릭한다.

이제 Microsoft.AspNetCore.Mvc.Versioning 패키지가 프로젝트 참조에 추가 되었다.

버전 관리 서비스 구성

그런 다음 Web API 프로젝트의 Program.cs를 아래와 같이 변경한한다.

//  using을 추가
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// 아래 행을 추가
builder.Services.AddApiVersioning(options =>
{
   options.ReportApiVersions = true;
   options.DefaultApiVersion = new ApiVersion(1, 0);
});

var app = builder.Build();

// 이하 생략

ReportAPIVersions 속성을 true로 설정하면 API가 응답 헤더에서 버전을 반환할 수 있다. 이 옵션을 켜고 API를 호출하면 api-supported-version에 버전 번호가 설정된다.

API에 버전 관리 적용

여기에서는, Web API의 프로젝트를 신규 작성했을 때에, 자동으로 작성되는 WeatherForecastController 를 예로 취한다.

먼저 Controllers 폴더에 V1 폴더를 만들고 WeatherForecastController.cs 를 이동한다.

이러한 작업을 솔루션 탐색기에서 수행하면 네임스페이스도 자동으로 변경된다.

namespace WebApiExample.Controllers.V1
{
   ...

이 컨트롤러 클래스에 버전 관리를 적용한다.

    [ApiController]
   [ApiVersion("1.0")]
   [Route("api/v{version:apiVersion}/[controller]")]
   public class WeatherForecastController : ControllerBase
   {
       ...

[ApiVersion] 속성을 추가하고 [Route] 속성을 변경한다.

움직여 보자

F5 키를 눌러 디버깅해 본다. 브라우저가 시작되므로 여기에서 아래 URL을 지정한다.

https://localhost:7174/api/v1/weatherforecast 

※ 7174의 포트 번호는 환경에 따라 다를 수 있다.

브라우저에 json이 표시되면 성공이다.

끝으로

아주 쉽게 API 버전 관리가 가능하다.

Version2를 추가하면 V2 폴더를 만들고 Version2용 WeatherForecastController.cs을 추가하면 된다.

파일명이나 클래스명을 변경할 필요가 없기 때문에 관리가 매우 편해진다.

덤

Program.cs를 아래와 같이 하면 URL이 아니라 QueryString 이나 Header에서 버전 정보를 지정할 수도 있는 것 같다.

using Microsoft.AspNetCore.Mvc.Versioning;

... 생략 ...

builder.Services.AddApiVersioning(options =>
{
   options.ReportApiVersions = true;
   options.DefaultApiVersion = new ApiVersion(1, 0);
   options.ApiVersionReader = ApiVersionReader.Combine(
       new QueryStringApiVersionReader("api-version"),
       new HeaderApiVersionReader("X-version")
   );
});