Jak korzystać z obsługi wersji interfejsu API w ASP.NET Core

Podczas tworzenia interfejsów API należy pamiętać o jednej rzeczy: zmiana jest nieunikniona. Gdy Twój interfejs API osiągnie punkt, w którym musisz dodać więcej obowiązków, powinieneś rozważyć wersjonowanie swojego interfejsu API. Dlatego będziesz potrzebować strategii wersjonowania.

Istnieje kilka podejść do wersjonowania interfejsów API, a każdy z nich ma swoje wady i zalety. W tym artykule omówiono wyzwania związane z wersjonowaniem interfejsów API i sposób pracy z pakietem obsługi wersji MVC ASP.NET Core firmy Microsoft do tworzenia wersji interfejsów API RESTful wbudowanych w ASP.NET Core. Możesz przeczytać więcej o wersjonowaniu Web API w moim poprzednim artykule tutaj. 

Utwórz projekt interfejsu API ASP.NET Core 3.1

Po pierwsze, utwórzmy projekt ASP.NET Core w programie Visual Studio. Zakładając, że w systemie jest zainstalowany program Visual Studio 2019, wykonaj czynności opisane poniżej, aby utworzyć nowy projekt ASP.NET Core w programie Visual Studio.

  1. Uruchom środowisko IDE programu Visual Studio.
  2. Kliknij „Utwórz nowy projekt”.
  3. W oknie „Utwórz nowy projekt” wybierz „Aplikacja sieci Web ASP.NET Core” z wyświetlonej listy szablonów.
  4. Kliknij Następny.
  5. W oknie „Konfiguruj nowy projekt” pokazanym obok podaj nazwę i lokalizację nowego projektu.
  6. Kliknij Utwórz.
  7. W oknie „Tworzenie nowej aplikacji sieci Web ASP.NET Core” wybierz .NET Core jako środowisko uruchomieniowe i ASP.NET Core 3.1 (lub nowszy) z listy rozwijanej u góry. Będę tutaj używać ASP.NET Core 3.1.
  8. Wybierz „API” jako szablon projektu, aby utworzyć nową aplikację ASP.NET Core API. 
  9. Upewnij się, że pola wyboru „Włącz obsługę Dockera” i „Konfiguruj dla HTTPS” są odznaczone, ponieważ nie będziemy tutaj używać tych funkcji.
  10. Upewnij się, że uwierzytelnianie jest ustawione na „Brak uwierzytelniania”, ponieważ nie będziemy też używać uwierzytelniania.
  11. Kliknij Utwórz. 

Spowoduje to utworzenie nowego projektu interfejsu API ASP.NET Core w programie Visual Studio. Wybierz folder Controllers solution w oknie Solution Explorer i kliknij „Dodaj -> Kontroler…”, aby utworzyć nowy kontroler o nazwie DefaultController.

Zastąp kod źródłowy klasy DefaultController następującym kodem.

    [Route („api / [controller]”)]

    [ApiController]

    public class DefaultController: ControllerBase

    {

        ciąg [] autorzy = nowy ciąg []

        {„Joydip Kanjilal”, „Steve Smith”, „Stephen Jones”};

        [HttpGet]

        public IEnumerable Get ()

        {

            powrót autorów;

        }

    }

Użyjemy tego kontrolera w kolejnych sekcjach tego artykułu.

Aby zaimplementować przechowywanie wersji interfejsu API w ASP.NET Core, należy wykonać następujące czynności:

  1. Zainstaluj pakiet wersji ASP.NET Core MVC.
  2. Skonfiguruj przechowywanie wersji interfejsu API w klasie Startup.
  3. Opisz kontrolery i akcje odpowiednimi atrybutami.

Zainstaluj pakiet wersji ASP.NET Core MVC

ASP.NET Core zapewnia obsługę wersji API natychmiast po wyjęciu z pudełka. Aby skorzystać z wersjonowania API, wystarczy zainstalować pakiet Microsoft.AspNetCore.Mvc.Versioning z NuGet. Możesz to zrobić za pośrednictwem menedżera pakietów NuGet w środowisku IDE programu Visual Studio 2019 lub wykonując następujące polecenie w konsoli Menedżera pakietów NuGet:

Zainstaluj pakiet Microsoft.AspNetCore.Mvc.Versioning

Zwróć uwagę, że jeśli korzystasz z interfejsu API sieci Web ASP.NET, należy dodać pakiet Microsoft.AspNet.WebApi.Versioning.

Skonfiguruj przechowywanie wersji interfejsu API w ASP.NET Core

Teraz, gdy pakiet niezbędny do obsługi wersji interfejsu API został zainstalowany w projekcie, można skonfigurować przechowywanie wersji interfejsu API w metodzie ConfigureServices klasy Startup. Poniższy fragment kodu ilustruje, jak można to osiągnąć.

public void ConfigureServices (usługi IServiceCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

Gdy wysyłasz żądanie Get do swojego API, zostanie wyświetlony błąd pokazany na rysunku 1.

Aby rozwiązać ten błąd, możesz określić wersję domyślną podczas dodawania usług zarządzania wersjami interfejsu API do kontenera. Możesz również chcieć użyć wersji domyślnej, jeśli wersja nie jest określona w żądaniu. Poniższy fragment kodu pokazuje, jak ustawić domyślną wersję na 1.0 przy użyciu właściwości AssumeDefaultVersionWhenUnspecified, jeśli informacje o wersji nie są dostępne w żądaniu.

services.AddApiVersioning (config =>

{

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

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Zwróć uwagę, jak wersja główna i wersja pomocnicza są przekazywane do konstruktora klasy ApiVersion w momencie przypisywania wersji domyślnej. Właściwość AssumeDefaultVersionWhenUnspecified może zawierać wartości true lub false. Jeśli to prawda, domyślna wersja określona podczas konfigurowania wersji interfejsu API zostanie użyta, jeśli nie są dostępne żadne informacje o wersji.

Pełny kod źródłowy metody ConfigureServices jest podany poniżej w celach informacyjnych.

public void ConfigureServices (usługi IServiceCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

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

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Ponieważ nie określono żadnych informacji o wersji, wszystkie punkty końcowe będą miały domyślną wersję 1.0.

Zgłoś wszystkie obsługiwane wersje swojego interfejsu API

Możesz chcieć poinformować klientów interfejsu API o wszystkich obsługiwanych wersjach. Aby to zrobić, należy skorzystać z właściwości ReportApiVersions, jak pokazano we fragmencie kodu podanym poniżej.

services.AddApiVersioning (config =>

{

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

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Użyj wersji w kontrolerze i metodach akcji

Teraz dodajmy kilka obsługiwanych wersji do naszego kontrolera, używając atrybutów, jak pokazano we fragmencie kodu podanym poniżej.

    [Route („api / [controller]”)]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion („1.1”)]

    [ApiVersion („2.0”)]

    public class DefaultController: ControllerBase

    {

        ciąg [] autorzy = nowy ciąg []

        {„Joydip Kanjilal”, „Steve Smith”, „Anand John”};

        [HttpGet]

        public IEnumerable Get ()

        {

            powrót autorów;

        }

    }

W przypadku wysyłania żądania Get z klienta HTTP, takiego jak Postman, oto sposób zgłaszania wersji.

Możesz również zgłosić przestarzałe wersje. Aby to zrobić, należy przekazać dodatkowy parametr do metody ApiVersion, jak pokazano we fragmencie kodu podanym poniżej.

[ApiVersion ("1.0", Deprecated = true)]

Odwzoruj na określoną wersję metody akcji

Istnieje inny ważny atrybut o nazwie MapToApiVersion. Możesz go użyć do odwzorowania na określoną wersję metody akcji. Poniższy fragment kodu pokazuje, jak można to osiągnąć.

[HttpGet („{id}”)]

[MapToApiVersion ("2.0")]

publiczny ciąg Get (int id)

{

   zwracanie autorów [id];

}

Kompletny przykład wersjonowania interfejsu API w ASP.NET Core

Oto pełny kod źródłowy DefaultController w celach informacyjnych.

[Route („api / [controller]”)]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion („1.1”)]

[ApiVersion („2.0”)]

public class DefaultController: ControllerBase

{

  ciąg [] autorzy = nowy ciąg []

  {„Joydip Kanjilal”, „Steve Smith”, „Stephen Jones”};

  [HttpGet]

  public IEnumerable Get ()

  {

      powrót autorów;

  }

  [HttpGet („{id}”)]

  [MapToApiVersion ("2.0")]

  publiczny ciąg Get (int id)

  {

     zwracanie autorów [id];

  }

}

Strategie obsługi wersji interfejsu API w ASP.NET Core

Istnieje kilka sposobów na utworzenie wersji interfejsu API w ASP.NET Core. W tej sekcji omówimy każdy z nich.

Przekaż informacje o wersji jako parametry QueryString

W takim przypadku zazwyczaj przekazujesz informacje o wersji jako część ciągu zapytania, jak pokazano w adresie URL podanym poniżej.

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

Przekaż informacje o wersji w nagłówkach HTTP

Jeśli chcesz przekazywać informacje o wersji w nagłówkach HTTP, powinieneś ustawić je w metodzie ConfigureServices, jak pokazano we fragmencie kodu podanym poniżej.

services.AddApiVersioning (config =>

{

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

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

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

});

Po skonfigurowaniu można wywołać metodę akcji dotyczącą określonej wersji interfejsu API, jak pokazano na rysunku 3.

Przekaż informacje o wersji w adresie URL

Jeszcze inną metodą przekazywania informacji o wersji jest przekazywanie informacji o wersji w ramach trasy. Jest to najprostszy sposób na wersjonowanie interfejsu API, ale istnieją pewne zastrzeżenia. Po pierwsze, jeśli korzystasz z tej strategii, Twoi klienci będą musieli aktualizować adres URL za każdym razem, gdy zostanie wydana nowa wersja interfejsu API. W konsekwencji takie podejście łamie podstawową zasadę REST, która mówi, że adres URL określonego zasobu nigdy nie powinien się zmieniać.

Aby zaimplementować tę strategię wersjonowania, należy określić informacje o trasie w kontrolerze, jak pokazano poniżej.

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

Poniższa lista kodu pokazuje, jak można to ustawić w klasie kontrolera.

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

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion („1.1”)]

public class DefaultController: ControllerBase

    {

        ciąg [] autorzy = nowy ciąg []

        {„Joydip Kanjilal”, „Steve Smith”, „Stephen Jones”};

        [HttpGet]

        public IEnumerable Get ()

        {

            powrót autorów;

        }

        [HttpGet („{id}”)]

        [MapToApiVersion ("2.0")]

        publiczny ciąg Get (int id)

        {

            zwracanie autorów [id];

        }

    }

Oto, jak możesz wywołać domyślny protokół HTTP, aby uzyskać metodę klasy DefaultController.

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

Aby wywołać inną metodę HTTP GET, tj. Tę, która akceptuje parametr, określ następujące elementy w przeglądarce internetowej lub w kliencie HTTP, takim jak Postman.

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

Wycofaj jedną lub więcej wersji swojego interfejsu API

Załóżmy, że masz wiele wersji swojego interfejsu API, ale chcesz wycofać jedną lub więcej z nich. Możesz to łatwo zrobić - wystarczy, że ustawisz właściwość Deprecated klasy ApiVersionAttribute na true, jak pokazano we fragmencie kodu podanym poniżej.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", Deprecated = true)]

[ApiVersion („2.0”)]

public class DefaultController: ControllerBase

{

     // Zwykły kod

}

Wersja API w ASP.NET Core jest teraz bezproblemowa dzięki wprowadzeniu pakietu Microsoft.AspNetCore.Mvc.Versioning. Istnieje kilka sposobów na wersję API - wystarczy wybrać najlepszą strategię w oparciu o swoje wymagania. Możesz również użyć wielu schematów wersji dla swojego interfejsu API. Daje to dużą elastyczność, ponieważ klienci mogą wybrać dowolny z obsługiwanych schematów wersjonowania.

Jak zrobić więcej w ASP.NET Core:

  • Jak używać obiektów transferu danych w ASP.NET Core 3.1
  • Jak obsługiwać błędy 404 w ASP.NET Core MVC
  • Jak używać iniekcji zależności w filtrach akcji w ASP.NET Core 3.1
  • Jak używać wzorca opcji w ASP.NET Core
  • Jak używać routingu punktów końcowych w ASP.NET Core 3,0 MVC
  • Jak wyeksportować dane do programu Excel w ASP.NET Core 3,0
  • Jak używać LoggerMessage w ASP.NET Core 3,0
  • Jak wysyłać wiadomości e-mail w ASP.NET Core
  • Jak rejestrować dane w programie SQL Server w ASP.NET Core
  • Jak planować zadania przy użyciu Quartz.NET w ASP.NET Core
  • Jak zwrócić dane z ASP.NET Core Web API
  • Jak sformatować dane odpowiedzi w ASP.NET Core
  • Jak korzystać z ASP.NET Core Web API przy użyciu RestSharp
  • Jak wykonywać operacje asynchroniczne przy użyciu Dapper
  • Jak używać flag funkcji w ASP.NET Core
  • Jak używać atrybutu FromServices w ASP.NET Core
  • Jak pracować z plikami cookie w ASP.NET Core
  • Jak pracować z plikami statycznymi w ASP.NET Core
  • Jak używać oprogramowania pośredniczącego ponownego zapisywania adresów URL w ASP.NET Core
  • Jak zaimplementować ograniczanie szybkości w ASP.NET Core
  • Jak używać usługi Azure Application Insights w ASP.NET Core
  • Korzystanie z zaawansowanych funkcji NLog w ASP.NET Core
  • Jak obsługiwać błędy w ASP.NET Web API
  • Jak zaimplementować globalną obsługę wyjątków w ASP.NET Core MVC
  • Jak obsługiwać wartości null w ASP.NET Core MVC
  • Zaawansowane przechowywanie wersji w ASP.NET Core Web API
  • Jak pracować z usługami roboczymi w ASP.NET Core
  • Jak używać interfejsu API ochrony danych w ASP.NET Core
  • Jak używać warunkowego oprogramowania pośredniczącego w ASP.NET Core
  • Jak pracować ze stanem sesji w ASP.NET Core
  • Jak pisać wydajne kontrolery w ASP.NET Core