ASP.NET Core 6 introduces a simplified hosting model that allows us to build lightweight APIs with minimal dependencies. We have discussed getting started with minimal APIs, using logging and dependency injection with minimal APIs, and testing minimal APIs in previous article here. In this article, we’ll examine how we can implement versioning for our minimal API endpoints.We’ll illustrate how we can version minimal APIs in ASP.NET 6 Core by following this sequence of six steps:
Create a ASP.NET 6 Core Minimal API project in Visual Studio 2022
Install the necessary NuGet package(s)
Add API versioning support to our project
Create a version set
Create API endpoints and associate the version set
Execute the API endpoints in Postman
To work with the code examples provided in this article, you should have Visual Studio 2022 installed in your system. If you don’t already have a copy, you can download Visual Studio 2022 here.Create an ASP.NET Core 6 minimal Web API project in Visual Studio 2022First off, let’s create an ASP.NET Core 6 project in Visual Studio. Following these steps will create a new ASP.NET Core 6 Web API project in Visual Studio 2022:
Launch the Visual Studio 2022 IDE.
Click on “Create new project.”
In the “Create new project” window, select “ASP.NET Core Web API” from the list of templates displayed.
Click Next.
In the “Configure your new project” window, specify the name and location for the new project.
Optionally check the “Place solution and project in the same directory” check box, depending on your preferences.
Click Next.
In the “Additional Information” window shown next, uncheck the check box that says “Use controllers…” since we’ll be using minimal APIs in this example. Leave the “Authentication Type” as “None” (default).
Ensure that the check boxes “Enable Docker,” “Configure for HTTPS,” and “Enable Open API Support” are unchecked as we won’t be using any of those features here.
Click Create.
We’ll use this ASP.NET Core 6 Web API project to create minimal API endpoints and implement API versioning in the sections below.Install the API versioning NuGet packagesASP.NET Core 6 minimal APIs support versioning using any of these three packages:
Asp.Versioning.Http — used to provide support for versioning in minimal APIs.
Asp.Versioning.Mvc — used to provide support for versioning in MVC Core apps.
Asp.Versioning.Mvc.ApiExplorer — used to provide support in the API explorer extensions for ASP.NET Core API versioning
If you have successfully created an ASP.NET Core 6 web application project in Visual Studio 2022, the next thing you should do is add the necessary NuGet packages to your project. To do this, select the project in the Solution Explorer window, right-click, and select “Manage NuGet Packages….” In the NuGet Package Manager window, search for the following package and install it.Asp.Versioning.HttpAlternatively, you can install the package via the NuGet Package Manager Console as shown below. PM> Install-Package Asp.Versioning.HttpAdd API versioning support to the services collection in ASP.NET Core 6To add API versioning support in the services collection for the minimal API, you should write the following code in the Program.cs file:builder.Services.AddApiVersioning(options =>{ options.DefaultApiVersion = new ApiVersion(1, 0); options.ReportApiVersions = true; options.AssumeDefaultVersionWhenUnspecified = true; options.ApiVersionReader = new HeaderApiVersionReader(“api-version”);});Note how the default API version has been specified. The ApiVersionReader property is used to specify the key that will be used by the client to pass the API version when calling the API endpoints. When the value of the AssumeDefaultVersionWhenUnspecified property is true, the default API version will be used if the client has not specified an API version.Note that you can combine HeaderApiVersionReader and QueryStringApiVersionReader to enable clients to specify version information in multiple ways when calling the API endpoints.services.AddApiVersioning(options =>{ options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ReportApiVersions = true; options.ApiVersionReader = ApiVersionReader.Combine( new HeaderApiVersionReader(“Api-Version”), new QueryStringApiVersionReader(“Query-String-Version”));});Add API versions using a version set in ASP.NET Core 6Now define a new version set for your API using the following code. var versionSet = app.NewApiVersionSet() .HasApiVersion(1.0) .HasApiVersion(2.0) .ReportApiVersions() .Build();We’ll use this version set in the next section to create our API endpoints.Create minimal API endpoints in ASP.NET Core 6We’ll create two endpoints here to keep it simple and focus on versioning our minimal APIs. Write the following code in the Program.cs file to create two endpoints.app.MapGet(“/GetMessage”, () => “This is an example of a minimal API”).WithApiVersionSet(versionSet).MapToApiVersion(1.0);app.MapGet(“/GetText”, () => “This is yet another example of a minimal API”).WithApiVersionSet(versionSet).WithApiVersionSet(versionSet).IsApiVersionNeutral();Note how we have associated the version set that we created in the previous section. The MapToApiVersion method maps a particular endpoint to a specific version. The IsApiVersionNeutral method marks an endpoint as neutral to API versioning.Here is the complete source code of the Program.cs file for your reference: using Asp.Versioning;using Asp.Versioning.Conventions;var builder = WebApplication.CreateBuilder(args);// Add services to the container.builder.Services.AddApiVersioning(options =>{ options.DefaultApiVersion = new ApiVersion(1, 0); options.ReportApiVersions = true; options.AssumeDefaultVersionWhenUnspecified = true; options.ApiVersionReader = new HeaderApiVersionReader(“api-version”);});var app = builder.Build();var versionSet = app.NewApiVersionSet() .HasApiVersion(1.0) .HasApiVersion(2.0) .ReportApiVersions() .Build();// Configure the HTTP request pipeline.app.MapGet(“/GetMessage”, () => “This is an example of a minimal API”).WithApiVersionSet(versionSet).HasApiVersion(new ApiVersion(2, 0));app.MapGet(“/GetText”, () => “This is another example of a minimal API”).WithApiVersionSet(versionSet).IsApiVersionNeutral();app.Run();Execute the minimal API endpointsNow press the F5 key in Visual Studio 2022 IDE to run the application. The following screenshot (Figure 1) shows the error you will encounter if you call the /getmessage endpoint without specifying the API version key in the request header. IDG
Figure 1. The /getmessage endpoint throws an error because no API version is specified.
The next screenshot (Figure 2) shows how the output will look when you specify the API version key in the request header and call the /getmessage endpoint again. IDG
Figure 2. The /getmessage endpoint runs successfully because the API version key is specified in the request header.
Because the /gettext endpoint is marked as API version neutral, you don’t need to specify an API version when calling this endpoint. When you execute the /gettext endpoint, the response will look like that shown in the screenshot (Figure 3) below. IDG
Figure 3. The /gettext method executes without having to specify an API version in the request header.
This being a minimal implementation, we have not used a data context, a database, a repository class, or even any model classes. We have merely defined two simple API endpoints to illustrate how we can version minimal APIs in ASP.NET Core 6.
Copyright © 2022 IDG Communications, Inc.
Source link