API versioning in .NET 8.0 is essential for maintaining backward compatibility and facilitating new feature releases. This guide will cover the basics, followed by more advanced techniques and best practices.
1. Getting Started with API Versioning
Start by adding the necessary NuGet package:
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
Then, configure API versioning in `Program.cs`:
builder.Services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
});
2. Basic API Versioning
a. URL Segment Versioning
In this method, the version is specified in the URL path.
Example:
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult GetV1() => Ok("Version 1");
[HttpGet, MapToApiVersion("2.0")]
public IActionResult GetV2() => Ok("Version 2");
}
In the example above, the endpoints will be accessible at:
- `GET /api/v1/products`
- `GET /api/v2/products`
b. Query String Versioning
Here, the API version is provided as a query parameter:
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = new QueryStringApiVersionReader("v");
});
Then, adjust your route attributes:
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult GetV1() => Ok("Version 1");
[HttpGet, MapToApiVersion("2.0")]
public IActionResult GetV2() => Ok("Version 2");
}
The endpoints will be accessible as:
- `GET /api/products?v=1.0`
- `GET /api/products?v=2.0`
c. Header Versioning
In header versioning, the API version is specified in the request headers.
Example setup in `Program.cs`:
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
});
Use the same controller setup as above. The API version is now passed through the header:
- `GET /api/products` with header `x-api-version: 1.0`
- `GET /api/products` with header `x-api-version: 2.0`
3. Advanced API Versioning
a. Using Conventions
You can set up versioning conventions without explicitly decorating each controller.
builder.Services.AddControllers()
.AddMvcOptions(options => options.Conventions.Add(new ApiVersionConventionBuilder()
.Controller<ProductsController>()
.HasApiVersion(1, 0)
.HasApiVersion(2, 0)));
b. Deprecating API Versions
You may deprecate older API versions to encourage clients to migrate to newer versions:
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
// actions here
}
Clients will receive a deprecation warning for using the older API version.
4. Best Practices for API Versioning
- Plan Versioning Early: Integrate versioning from the start to avoid breaking changes later.
- Document Versions: Clearly document the available versions and their differences.
- Graceful Deprecation: Provide ample time and communication before deprecating any versions.
- Monitor Usage: Track which versions are most used to inform future deprecations.
5. Conclusion
API versioning in .NET 8.0 is a robust feature that allows for the seamless evolution of your APIs. Whether using URL segments, query strings, or headers, .NET 8.0 provides the flexibility needed to manage different API versions effectively.
Implementing these techniques will ensure that your application remains flexible, scalable, and future-proof.
Additional Resources:
- [Microsoft Docs: API Versioning](https://docs.microsoft.com/en-us/aspnet/core/web-api/advanced/versioning?view=aspnetcore-8.0)
- [GitHub: API Versioning Examples](https://github.com/microsoft/aspnet-api-versioning)
