Listen to this Post
API versioning is a technique used to manage changes in an API while maintaining backward compatibility for existing clients. It allows developers to introduce new features, fix bugs, or modify the API without impacting the functionality of existing integrations.
API is software. Every piece of software needs updates at some point. When creating updates for your API, you need to ensure that the changes don’t affect your API consumers (users). To ensure that, you need to implement API versioning.
Read more about API Versioning in Controllers here
You Should Know: Practical API Versioning Implementation
Here are key commands and code examples for implementing API versioning in .NET:
1. Install required NuGet package
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
2. Configure API versioning in Program.cs
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
3. Versioning via URL path segment
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/[bash]")]
public class ProductsController : ControllerBase
{
[bash]
public IActionResult Get() => Ok("Version 1");
}
4. Versioning via query string
[ApiVersion("2.0")]
[Route("[bash]")]
public class ProductsV2Controller : ControllerBase
{
[bash]
public IActionResult Get() => Ok("Version 2");
}
5. Versioning via headers
curl -X GET https://api.example.com/products -H "X-API-Version: 2.0"
6. Deprecating old versions
[ApiVersion("1.0", Deprecated = true)]
public class ProductsController : ControllerBase
{
// Controller actions
}
7. Linux commands to test API versions
Test version 1.0 curl https://api.example.com/v1.0/products Test version 2.0 curl https://api.example.com/v2.0/products Check API versions available curl -I https://api.example.com/products
8. Windows PowerShell commands for API testing
Test version 1.0
Invoke-RestMethod -Uri "https://api.example.com/v1.0/products" -Method Get
Test version 2.0 with headers
$headers = @{"X-API-Version" = "2.0"}
Invoke-RestMethod -Uri "https://api.example.com/products" -Method Get -Headers $headers
What Undercode Say
API versioning is crucial for maintaining stable integrations while evolving your services. The key approaches include URL path versioning, query string versioning, and header versioning. Each method has its pros and cons:
- URL path versioning (
/v1/products) is most explicit but breaks URLs - Query string versioning (
/products?api-version=1.0) is flexible but less visible - Header versioning keeps URLs clean but requires client cooperation
For Linux/Windows administrators working with APIs, remember these key commands:
Check API version support curl -s -I https://api.example.com/products | grep -i "api-supported-versions" Batch test multiple versions for version in 1 2 3; do curl -s "https://api.example.com/v$version/products"; done
In PowerShell:
Test all supported versions
1..3 | ForEach-Object {
$response = Invoke-RestMethod "https://api.example.com/v$_/products" -ErrorAction SilentlyContinue
if ($response) { Write-Host "Version $_ works: $response" }
}
Always document your versioning strategy clearly and provide migration paths for clients. Consider using API gateways to manage version routing and implement proper monitoring to track version usage.
Expected Output:
{
"apiVersion": "1.0",
"status": "success",
"data": {
"message": "Version 1 response"
}
}
References:
Reported By: Djokic Stefan – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
