Jak používat správu verzí API v ASP.NET Core

Při vývoji API byste měli mít na paměti jednu věc: Změna je nevyhnutelná. Když vaše API dosáhlo bodu, kdy potřebujete přidat další odpovědnosti, měli byste zvážit verzi vašeho API. Proto budete potřebovat strategii verzí.

Existuje několik přístupů k verzování API a každý z nich má své klady a zápory. Tento článek pojednává o výzvách verzování API a o tom, jak můžete pracovat s balíčkem Microsoft ASP.NET Core MVC Versioning to version RESTful APIs built in ASP.NET Core. Více o verzích webového API si můžete přečíst v mém předchozím článku zde.

Vytvořte projekt API ASP.NET Core 3.1

Nejprve si vytvořme projekt ASP.NET Core v sadě Visual Studio. Za předpokladu, že je ve vašem systému nainstalovaná sada Visual Studio 2019, postupujte podle níže uvedených kroků a vytvořte nový projekt ASP.NET Core v sadě Visual Studio.

Spusťte Visual Studio IDE.
Klikněte na „Vytvořit nový projekt“.
V okně „Vytvořit nový projekt“ vyberte ze zobrazeného seznamu šablon „Webová aplikace ASP.NET Core“.
Klikněte na Další.
V dalším okně „Konfigurace nového projektu“ zadejte název a umístění nového projektu.
Klikněte na Vytvořit.
V okně „Vytvořit novou webovou aplikaci ASP.NET Core“ vyberte jako běhový modul .NET Core a v rozevíracím seznamu nahoře vyberte ASP.NET Core 3.1 (nebo novější). Budu zde používat ASP.NET Core 3.1.
Vyberte „API“ jako šablonu projektu a vytvořte novou aplikaci API ASP.NET Core.
Ujistěte se, že políčka „Povolit podporu Dockeru“ a „Konfigurovat pro HTTPS“ nejsou zaškrtnuta, protože zde tyto funkce nebudeme používat.
Ujistěte se, že je ověřování nastaveno na „Žádné ověřování“, protože také nebudeme používat ověřování.
Klikněte na Vytvořit.

Tím se vytvoří nový projekt rozhraní API ASP.NET Core v sadě Visual Studio. Vyberte složku řešení Controllers v okně Solution Explorer a kliknutím na „Přidat -> Controller ...“ vytvořte nový řadič s názvem DefaultController.

Nahraďte zdrojový kód třídy DefaultController následujícím kódem.

  [Route ("api / [controller]")]
  [ApiController]
  veřejná třída DefaultController: ControllerBase
    {
  řetězec [] autoři = nový řetězec []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
        {
  vrátit autory;
        }
    }

Tento ovladač použijeme v následujících částech tohoto článku.

Chcete-li implementovat správu verzí API v ASP.NET Core, musíte provést následující:

Nainstalujte balíček správy verzí ASP.NET Core MVC.
Nakonfigurujte správu verzí API ve třídě Startup.
Anotujte řadiče a akce příslušnými atributy.

Nainstalujte balíček správy verzí ASP.NET Core MVC

ASP.NET Core poskytuje podporu pro verzování rozhraní API out-of-the-box. Chcete-li využít verzování API, vše, co musíte udělat, je nainstalovat balíček Microsoft.AspNetCore.Mvc.Versioning z NuGet. Můžete to udělat buď prostřednictvím správce balíčků NuGet uvnitř IDE sady Visual Studio 2019, nebo provedením následujícího příkazu v konzole správce balíčků NuGet:

Instalační balíček Microsoft.AspNetCore.Mvc.Versioning

Pokud používáte webové rozhraní ASP.NET, měli byste přidat balíček Microsoft.AspNet.WebApi.Versioning.

Nakonfigurujte správu verzí API v ASP.NET Core

Teď, když byl ve vašem projektu nainstalován balíček nezbytný pro správu verzí vašeho API, můžete nakonfigurovat správu verzí API v metodě ConfigureServices třídy Startup. Následující fragment kódu ukazuje, jak toho lze dosáhnout.

public void ConfigureServices (služby IServiceCollection)
{
  services.AddControllers ();
  services.AddApiVersioning ();
}

Když zadáte požadavek na získání API, zobrazí se vám chyba uvedená na obrázku 1.

Chcete-li vyřešit tuto chybu, můžete určit výchozí verzi při přidávání služeb správy verzí API do kontejneru. Možná také budete chtít použít výchozí verzi, pokud v požadavku není uvedena verze. Následující fragment kódu ukazuje, jak můžete nastavit výchozí verzi na 1,0 pomocí vlastnosti AssumeDefaultVersionWhenUnspecified, pokud informace o verzi nejsou v požadavku k dispozici.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nová ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
});

Všimněte si, jak se hlavní verze a vedlejší verze předávají konstruktoru třídy ApiVersion v době přiřazení výchozí verze. Vlastnost AssumeDefaultVersionWhenUnspecified může obsahovat hodnoty true nebo false. Pokud je to pravda, použije se výchozí verze zadaná při konfiguraci správy verzí API, pokud nejsou k dispozici žádné informace o verzi.

Kompletní zdrojový kód metody ConfigureServices je uveden níže pro vaši referenci.

public void ConfigureServices (služby IServiceCollection)
{
  services.AddControllers ();
  services.AddApiVersioning (config =>
    {
  config.DefaultApiVersion = nová ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

Protože jste nezadali žádné informace o verzi, budou mít všechny koncové body výchozí verzi 1.0.

Nahlaste všechny podporované verze vašeho API

Možná budete chtít informovat klienty rozhraní API o všech podporovaných verzích. Chcete-li to provést, měli byste využít výhod vlastnosti ReportApiVersions, jak je ukázáno v níže uvedeném fragmentu kódu.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nová ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
});

Použijte verze v ovladači a metody akce

Nyní přidáme několik podporovaných verzí do našeho řadiče pomocí atributů, jak je uvedeno ve fragmentu kódu uvedeném níže.

  [Route ("api / [controller]")]
  [ApiController]
  [ApiVersion ("1.0")]
  [ApiVersion ("1.1")]
  [ApiVersion ("2.0")]
  veřejná třída DefaultController: ControllerBase
    {
  řetězec [] autoři = nový řetězec []
  {"Joydip Kanjilal", "Steve Smith", "Anand John"};
  [HttpGet]
  public IEnumerable Get ()
        {
  vrátit autory;
        }
    }

Když zadáte požadavek na získání od klienta HTTP, jako je Postman, zde budou uvedeny verze těchto verzí.

Zastaralé verze můžete také nahlásit. Chcete-li to provést, měli byste předat další parametr metodě ApiVersion, jak je znázorněno v úryvku kódu uvedeném níže.

[ApiVersion ("1.0", zastaralé = true)]

Namapujte na konkrétní verzi metody akce

Existuje další důležitý atribut s názvem MapToApiVersion. Můžete jej použít k mapování na konkrétní verzi metody akce. Následující fragment kódu ukazuje, jak toho lze dosáhnout.

[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
veřejný řetězec Get (int id)
{
  vrátit autory [id];
}

Kompletní příklad správy verzí API v ASP.NET Core

Zde je kompletní zdrojový kód DefaultController pro vaši referenci.

[Route ("api / [controller]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
veřejná třída DefaultController: ControllerBase
{
  řetězec [] autoři = nový řetězec []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
  {
  vrátit autory;
  }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  veřejný řetězec Get (int id)
  {
  vrátit autory [id];
  }
}

Strategie správy verzí API v ASP.NET Core

Existuje několik způsobů, jak můžete verzi API v ASP.NET Core verzovat. V této části prozkoumáme všechny z nich.

Předejte informace o verzi jako parametry QueryString

V tomto případě byste obvykle předávali informace o verzi jako součást řetězce dotazu, jak je uvedeno v níže uvedené adrese URL.

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

Předejte informace o verzi v hlavičkách HTTP

Pokud chcete předat informace o verzi v hlavičkách HTTP, měli byste je nastavit v metodě ConfigureServices, jak je ukázáno ve fragmentu kódu uvedeném níže.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nová ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
  config.ApiVersionReader = nový HeaderApiVersionReader ("verze API");
});

Jakmile to bylo nastaveno, můžete vyvolat metodu akce týkající se konkrétní verze API, jak je znázorněno na obrázku 3.

Předejte informace o verzi v adrese URL

Ještě dalším způsobem předávání informací o verzi je předávání informací o verzi jako součásti trasy. Toto je nejjednodušší způsob verzování vašeho API, ale existují určitá upozornění. Nejprve, pokud použijete tuto strategii, vaši klienti budou muset aktualizovat adresu URL, kdykoli bude vydána nová verze API. V důsledku toho tento přístup porušuje základní princip REST, který uvádí, že URL konkrétního prostředku by se nikdy nemělo měnit.

Chcete-li implementovat tuto strategii správy verzí, měli byste zadat informace o trase v ovladači, jak je znázorněno níže.

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

Následující výpis kódu ukazuje, jak to můžete nastavit ve své třídě řadičů.

[Route ("api / v {verze: apiVersion} / [controller]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
veřejná třída DefaultController: ControllerBase
    {
  řetězec [] autoři = nový řetězec []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
        {
  vrátit autory;
        }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  veřejný řetězec Get (int id)
        {
  vrátit autory [id];
        }
    }

Zde je způsob, jak můžete volat výchozí HTTP, abyste získali metodu třídy DefaultController.

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

Chcete-li vyvolat další metodu HTTP GET, tj. Tu, která přijímá parametr, zadejte ve webovém prohlížeči nebo v klientovi HTTP, jako je Postman, následující.

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

Zastarejte jednu nebo více verzí vašeho API

Předpokládejme, že máte více verzí svého API, ale chcete ukončit podporu jedné nebo více z nich. Můžete to udělat snadno - stačí zadat Deprecated vlastnost třídy ApiVersionAttribute na true, jak je ukázáno v níže uvedeném fragmentu kódu.

[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1", zastaralé = true)]
[ApiVersion ("2.0")]
veřejná třída DefaultController: ControllerBase
{
  // Obvyklý kód
}

Verze verzí API v ASP.NET Core je nyní bezproblémová díky zavedení balíčku Microsoft.AspNetCore.Mvc.Versioning. Existuje několik způsobů, jak vytvořit verzi API - stačí se rozhodnout pro nejlepší strategii na základě vašich požadavků. Pro své API můžete také použít více schémat verzí. To dodává velkou flexibilitu, protože klienti si mohou vybrat kterékoli z podporovaných schémat verzí.