Setting Up API Versioning in ASP.NET Core Locally

With header versioning, clients pass the version in request headers:

[ApiController]
[Route("api/[controller]")]
[ApiVersion("1.0")]
public class CustomersController : ControllerBase
{
    [HttpGet]
    public IActionResult GetCustomers()
    {
        return Ok(new { Message = "Customers from API v1" });
    }
}

Clients need to include the version in the request headers:

GET /api/customers
X-Api-Version: 1.0

Best Practices for API Versioning and Backward Compatibility

1. Default API Version: Define a default version to serve requests that do not specify a version explicitly.
2. Deprecation Strategy: Mark old API versions as deprecated using [ApiVersion("1.0", Deprecated = true)].
3. Versioning Policy: Adopt a clear versioning policy (e.g., semantic versioning).
4. Testing: Ensure comprehensive testing of new versions to avoid regressions.
5. Client Communication: Notify clients before deprecating older versions.
6. API Documentation: Use tools like Swagger to document API versions.

Conclusion

API versioning in ASP.NET Core ensures flexibility and backward compatibility while introducing new changes. By leveraging Microsoft.AspNetCore.Mvc.Versioning, developers can efficiently implement versioning strategies like URL-based, query-string, and header-based approaches. Adopting best practices helps maintain seamless API evolution while minimizing disruptions for clients.

By following these strategies, you can ensure that your API remains scalable, maintainable, and user-friendly over time.

Sandip Mhaske

Senior Engineer • Author of 675 guides • Follow for System Design & .NET deep-dives

About