ASP.NET Core에서 API 버전 관리를 사용하는 방법

API를 개발할 때 한 가지 명심해야합니다. 변화는 불가피합니다. API가 더 많은 책임을 추가해야하는 시점에 도달하면 API 버전 관리를 고려해야합니다. 따라서 버전 관리 전략이 필요합니다.

API 버전 관리에는 여러 가지 접근 방식이 있으며 각각 장단점이 있습니다. 이 문서에서는 API 버전 관리의 문제와 Microsoft의 ASP.NET Core MVC 버전 관리 패키지를 사용하여 ASP.NET Core에서 빌드 된 RESTful API를 버전 관리하는 방법에 대해 설명합니다. 이전 기사에서 Web API 버전 관리에 대한 자세한 내용을 읽을 수 있습니다. 

ASP.NET Core 3.1 API 프로젝트 만들기

먼저 Visual Studio에서 ASP.NET Core 프로젝트를 만들어 보겠습니다. Visual Studio 2019가 시스템에 설치되어 있다고 가정하고 아래에 설명 된 단계에 따라 Visual Studio에서 새 ASP.NET Core 프로젝트를 만듭니다.

  1. Visual Studio IDE를 시작합니다.
  2. "새 프로젝트 만들기"를 클릭합니다.
  3. "새 프로젝트 만들기"창의 표시된 템플릿 목록에서 "ASP.NET Core 웹 애플리케이션"을 선택합니다.
  4. 다음을 클릭하십시오.
  5. 다음에 표시된 "새 프로젝트 구성"창에서 새 프로젝트의 이름과 위치를 지정합니다.
  6. 생성을 클릭합니다.
  7. "Create New ASP.NET Core Web Application"창에서 런타임으로 .NET Core를 선택하고 상단의 드롭 다운 목록에서 ASP.NET Core 3.1 (또는 그 이상)을 선택합니다. 여기서는 ASP.NET Core 3.1을 사용하겠습니다.
  8. 프로젝트 템플릿으로 "API"를 선택하여 새 ASP.NET Core API 애플리케이션을 만듭니다. 
  9. 여기서는 이러한 기능을 사용하지 않으므로 "Docker 지원 활성화"및 "HTTPS 용 구성"확인란이 선택 취소되어 있는지 확인합니다.
  10. 인증을 사용하지 않을 것이므로 인증이 "인증 없음"으로 설정되어 있는지 확인하십시오.
  11. 생성을 클릭합니다. 

그러면 Visual Studio에 새 ASP.NET Core API 프로젝트가 생성됩니다. 솔루션 탐색기 창에서 컨트롤러 솔루션 폴더를 선택하고“추가-> 컨트롤러…”를 클릭하여 DefaultController라는 새 컨트롤러를 만듭니다.

DefaultController 클래스의 소스 코드를 다음 코드로 바꿉니다.

    [Route ( "api / [controller]")]

    [ApiController]

    공용 클래스 DefaultController : ControllerBase

    {

        문자열 [] 작성자 = 새 문자열 []

        { "Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        공용 IEnumerable Get ()

        {

            저자 반환;

        }

    }

이 문서의 후속 섹션에서이 컨트롤러를 사용합니다.

ASP.NET Core에서 API 버전 관리를 구현하려면 다음을 수행해야합니다.

  1. ASP.NET Core MVC 버전 관리 패키지를 설치합니다.
  2. Startup 클래스에서 API 버전 관리를 구성합니다.
  3. 적절한 속성을 사용하여 컨트롤러 및 작업에 주석을 추가합니다.

ASP.NET Core MVC 버전 관리 패키지 설치

ASP.NET Core는 기본적으로 API 버전 관리를 지원합니다. API 버전 관리를 활용하려면 NuGet에서 Microsoft.AspNetCore.Mvc.Versioning 패키지를 설치하기 만하면됩니다. Visual Studio 2019 IDE 내의 NuGet 패키지 관리자를 통해 또는 NuGet 패키지 관리자 콘솔에서 다음 명령을 실행하여이 작업을 수행 할 수 있습니다.

설치 패키지 Microsoft.AspNetCore.Mvc.Versioning

ASP.NET Web API를 사용하는 경우 Microsoft.AspNet.WebApi.Versioning 패키지를 추가해야합니다.

ASP.NET Core에서 API 버전 관리 구성

이제 API 버전 관리에 필요한 패키지가 프로젝트에 설치되었으므로 Startup 클래스의 ConfigureServices 메서드에서 API 버전 관리를 구성 할 수 있습니다. 다음 코드 스 니펫은이를 달성하는 방법을 보여줍니다.

public void ConfigureServices (IServiceCollection 서비스)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

API에 Get 요청을하면 그림 1과 같은 오류가 표시됩니다.

이 오류를 해결하기 위해 API 버전 관리 서비스를 컨테이너에 추가 할 때 기본 버전을 지정할 수 있습니다. 요청에 버전이 지정되지 않은 경우 기본 버전을 사용할 수도 있습니다. 다음 코드 조각은 요청에서 버전 정보를 사용할 수없는 경우 AssumeDefaultVersionWhenUnspecified 속성을 사용하여 기본 버전을 1.0으로 설정하는 방법을 보여줍니다.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

기본 버전을 할당 할 때 주 버전과 부 버전이 ApiVersion 클래스의 생성자에 어떻게 전달되는지 확인합니다. AssumeDefaultVersionWhenUnspecified 속성은 true 또는 false 값을 보유 할 수 있습니다. true 인 경우 버전 정보를 사용할 수없는 경우 API 버전 관리를 구성 할 때 지정된 기본 버전이 사용됩니다.

ConfigureServices 메서드의 전체 소스 코드는 참조 용으로 아래에 제공됩니다.

public void ConfigureServices (IServiceCollection 서비스)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = new ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

버전 정보를 지정하지 않았으므로 모든 엔드 포인트의 기본 버전은 1.0입니다.

지원되는 모든 버전의 API보고

API 클라이언트에게 지원되는 모든 버전을 알리고 싶을 수 있습니다. 이렇게하려면 아래 제공된 코드 스 니펫에 표시된대로 ReportApiVersions 속성을 활용해야합니다.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = new ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

컨트롤러 및 작업 방법의 버전 사용

이제 아래 제공된 코드 스 니펫에 표시된대로 속성을 사용하여 컨트롤러에 지원되는 몇 가지 버전을 추가해 보겠습니다.

    [Route ( "api / [controller]")]

    [ApiController]

    [ApiVersion ( "1.0")]

    [ApiVersion ( "1.1")]

    [ApiVersion ( "2.0")]

    공용 클래스 DefaultController : ControllerBase

    {

        문자열 [] 작성자 = 새 문자열 []

        { "Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        공용 IEnumerable Get ()

        {

            저자 반환;

        }

    }

Postman과 같은 HTTP 클라이언트에서 Get 요청을 할 때 버전이보고되는 방법은 다음과 같습니다.

더 이상 사용되지 않는 버전도보고 할 수 있습니다. 이렇게하려면 아래에 제공된 코드 스 니펫에 표시된대로 ApiVersion 메서드에 추가 매개 변수를 전달해야합니다.

[ApiVersion ( "1.0", 지원 중단됨 = true)]

특정 버전의 작업 메서드에 매핑

MapToApiVersion이라는 또 다른 중요한 속성이 있습니다. 이를 사용하여 특정 버전의 작업 메서드에 매핑 할 수 있습니다. 다음 코드 스 니펫은이를 수행하는 방법을 보여줍니다.

[HttpGet ( "{id}")]

[MapToApiVersion ( "2.0")]

공개 문자열 Get (int id)

{

   return authors [id];

}

ASP.NET Core의 전체 API 버전 관리 예제

다음은 참조 용 DefaultController의 전체 소스 코드입니다.

[Route ( "api / [controller]")]

[ApiController]

[ApiVersion ( "1.0")]

[ApiVersion ( "1.1")]

[ApiVersion ( "2.0")]

공용 클래스 DefaultController : ControllerBase

{

  문자열 [] 작성자 = 새 문자열 []

  { "Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  공용 IEnumerable Get ()

  {

      저자 반환;

  }

  [HttpGet ( "{id}")]

  [MapToApiVersion ( "2.0")]

  공개 문자열 Get (int id)

  {

     return authors [id];

  }

}

ASP.NET Core의 API 버전 관리 전략

ASP.NET Core에서 API의 버전을 지정할 수있는 몇 가지 방법이 있습니다. 이 섹션에서는 각각에 대해 살펴 보겠습니다.

버전 정보를 QueryString 매개 변수로 전달

이 경우 일반적으로 아래 제공된 URL에 표시된 쿼리 문자열의 일부로 버전 정보를 전달합니다.

//localhost:25718/api/default?api-version=1.0

HTTP 헤더에 버전 정보 전달

HTTP 헤더에 버전 정보를 전달하려면 아래 제공된 코드 스 니펫에 표시된대로 ConfigureServices 메소드에서 설정해야합니다.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = new HeaderApiVersionReader ( "api-version");

});

이것이 설정되면 그림 3과 같이 특정 버전의 API와 관련된 작업 메서드를 호출 할 수 있습니다.

URL에 버전 정보 전달

버전 정보를 전달하는 또 다른 방법은 경로의 일부로 버전 정보를 전달하는 것입니다. 이것은 API 버전을 관리하는 가장 간단한 방법이지만 몇 가지주의 사항이 있습니다. 우선,이 전략을 사용하면 API의 새 버전이 출시 될 때마다 클라이언트가 URL을 업데이트해야합니다. 결과적으로이 접근 방식은 특정 리소스의 URL이 절대 변경되어서는 안된다는 REST의 기본 원칙을 위반합니다.

이 버전 관리 전략을 구현하려면 아래와 같이 컨트롤러에서 경로 정보를 지정해야합니다.

[Route ( "api / v {version : apiVersion} / [controller]")]

다음 코드 목록은 컨트롤러 클래스에서이를 설정하는 방법을 보여줍니다.

[Route ( "api / v {version : apiVersion} / [controller]")]

[ApiController]

[ApiVersion ( "1.0")]

[ApiVersion ( "1.1")]

공용 클래스 DefaultController : ControllerBase

    {

        문자열 [] 작성자 = 새 문자열 []

        { "Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        공용 IEnumerable Get ()

        {

            저자 반환;

        }

        [HttpGet ( "{id}")]

        [MapToApiVersion ( "2.0")]

        공개 문자열 Get (int id)

        {

            return authors [id];

        }

    }

다음은 DefaultController 클래스의 메서드를 가져 오기 위해 기본 HTTP를 호출하는 방법입니다.

//localhost:25718/api/v1.0/default

다른 HTTP GET 메소드, 즉 매개 변수를 허용하는 메소드를 호출하려면 웹 브라우저 또는 Postman과 같은 HTTP 클라이언트에서 다음을 지정하십시오.

//localhost:25718/api/v2.0/default/1

하나 이상의 API 버전 지원 중단

여러 버전의 API가 있지만 그중 하나 이상을 지원 중단하고 싶다고 가정합니다. 이 작업은 쉽게 수행 할 수 있습니다. 아래 제공된 코드 조각에 표시된대로 ApiVersionAttribute 클래스의 Deprecated 속성을 true로 지정하기 만하면됩니다.

[ApiController]

[ApiVersion ( "1.0")]

[ApiVersion ( "1.1", 지원 중단 = true)]

[ApiVersion ( "2.0")]

공용 클래스 DefaultController : ControllerBase

{

     // 일반 코드

}

Microsoft.AspNetCore.Mvc.Versioning 패키지의 도입 덕분에 ASP.NET Core의 API 버전 관리가 이제 원활 해졌습니다. API 버전을 지정하는 방법에는 여러 가지가 있습니다. 요구 사항에 따라 최상의 전략을 결정하기 만하면됩니다. API에 여러 버전 관리 체계를 사용할 수도 있습니다. 이는 클라이언트가 지원되는 버전 관리 체계를 선택할 수 있기 때문에 많은 유연성을 추가합니다.

ASP.NET Core에서 더 많은 작업을 수행하는 방법 :

  • ASP.NET Core 3.1에서 데이터 전송 개체를 사용하는 방법
  • ASP.NET Core MVC에서 404 오류를 처리하는 방법
  • ASP.NET Core 3.1의 작업 필터에서 종속성 주입을 사용하는 방법
  • ASP.NET Core에서 옵션 패턴을 사용하는 방법
  • ASP.NET Core 3.0 MVC에서 엔드 포인트 라우팅을 사용하는 방법
  • ASP.NET Core 3.0에서 Excel로 데이터를 내보내는 방법
  • ASP.NET Core 3.0에서 LoggerMessage를 사용하는 방법
  • ASP.NET Core에서 이메일을 보내는 방법
  • ASP.NET Core에서 SQL Server에 데이터를 기록하는 방법
  • ASP.NET Core에서 Quartz.NET을 사용하여 작업을 예약하는 방법
  • ASP.NET Core Web API에서 데이터를 반환하는 방법
  • ASP.NET Core에서 응답 데이터의 형식을 지정하는 방법
  • RestSharp를 사용하여 ASP.NET Core Web API를 사용하는 방법
  • Dapper를 사용하여 비동기 작업을 수행하는 방법
  • ASP.NET Core에서 기능 플래그를 사용하는 방법
  • ASP.NET Core에서 FromServices 특성을 사용하는 방법
  • ASP.NET Core에서 쿠키를 사용하는 방법
  • ASP.NET Core에서 정적 파일을 사용하는 방법
  • ASP.NET Core에서 URL 재 작성 미들웨어를 사용하는 방법
  • ASP.NET Core에서 속도 제한을 구현하는 방법
  • ASP.NET Core에서 Azure Application Insights를 사용하는 방법
  • ASP.NET Core에서 고급 NLog 기능 사용
  • ASP.NET Web API에서 오류를 처리하는 방법
  • ASP.NET Core MVC에서 전역 예외 처리를 구현하는 방법
  • ASP.NET Core MVC에서 null 값을 처리하는 방법
  • ASP.NET Core Web API의 고급 버전 관리
  • ASP.NET Core에서 작업자 서비스로 작업하는 방법
  • ASP.NET Core에서 데이터 보호 API를 사용하는 방법
  • ASP.NET Core에서 조건부 미들웨어를 사용하는 방법
  • ASP.NET Core에서 세션 상태로 작업하는 방법
  • ASP.NET Core에서 효율적인 컨트롤러를 작성하는 방법