Versioning ASP.NET Core Web API
💡 Concept Name
API Versioning in ASP.NET Core
📘 Quick Intro
As APIs evolve, changes can break older clients. API versioning solves this by allowing multiple versions to coexist, enabling smooth transitions. ASP.NET Core offers built-in support for API versioning via NuGet.
🧠 Analogy / Short Story
Think of an API like a restaurant menu. Over time, dishes change or get renamed. Versioning is like offering old and new menus side by side so loyal customers still get their favorite dishes, while new ones see the updated list.
🔧 Technical Explanation
ASP.NET Core supports API versioning using the `Microsoft.AspNetCore.Mvc.Versioning` package. You can version APIs in several ways:
- URL Segment:
/api/v1/products - Query String:
/api/products?api-version=1.0 - HTTP Header:
api-version: 1.0 - Media Type: Accept header with version info
Register API versioning in Program.cs or Startup.cs and annotate controllers with attributes like [ApiVersion("1.0")].
🎯 Purpose & Use Case
- ✅ Maintain backward compatibility for existing clients
- ✅ Allow controlled rollout of new API features
- ✅ Support microservices with independent versioning
- ✅ Avoid breaking changes in production systems
💻 Real Code Example
Setup API Versioning in ASP.NET Core:
// Program.cs
builder.Services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
});
// Controller
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult GetV1() => Ok("Product list from v1");
}
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult GetV2() => Ok("Product list from v2");
}
❓ Interview Q&A
Q1: Why is API versioning important?
A: It prevents breaking changes and ensures backward compatibility.
Q2: Which NuGet package enables versioning?
A: Microsoft.AspNetCore.Mvc.Versioning
Q3: Name three versioning strategies?
A: URL segment, Query string, Header-based
Q4: How to set a default version?
A: Use AssumeDefaultVersionWhenUnspecified = true
Q5: Can versioning be combined with Swagger?
A: Yes, via Swashbuckle filters or NSwag
Q6: What does ReportApiVersions do?
A: It adds supported/deprecated versions in response headers
Q7: What is Media Type versioning?
A: Version info sent in the Accept header
Q8: How to version multiple controllers?
A: Use different classes and attributes for each version
Q9: Is API versioning supported in minimal APIs?
A: Not natively as of now, custom handling is needed
Q10: Can we deprecate an API version?
A: Yes, using [Obsolete] or versioning metadata
📝 MCQs
Q1: What is the benefit of API versioning?
- A. Increase API complexity
- B. Enable backward compatibility
- C. Force immediate upgrades
- D. Disable old endpoints
Q2: Which of these is NOT a versioning method?
- A. URL Segment
- B. Query String
- C. HTTP Method
- D. Header-based
Q3: What attribute is used to define an API version?
- A. [RouteVersion]
- B. [ApiVersion]
- C. [VersionRoute]
- D. [HttpVersion]
Q4: What does setting AssumeDefaultVersionWhenUnspecified to true mean?
- A. API throws error if version is missing
- B. Uses default version if not provided
- C. API is skipped
- D. None of the above
Q5: What file is commonly used to register versioning settings?
- A. appsettings.json
- B. Program.cs
- C. Controller.cs
- D. launchSettings.json
Q6: What does ReportApiVersions do?
- A. Logs errors
- B. Returns supported versions in response headers
- C. Shows routes in Swagger
- D. None
Q7: Can you version different controllers independently?
- A. No
- B. Yes
- C. Only in Swagger
- D. Only using query string
Q8: What is a drawback of URL segment versioning?
- A. Easy to implement
- B. Breaks RESTful resource URLs
- C. Doesn’t work on mobile
- D. Increases performance
Q9: Which versioning strategy best hides versioning logic?
- A. URL-based
- B. Query string
- C. Header-based
- D. Extension method
Q10: Can you combine multiple versioning strategies?
- A. No
- B. Yes
- C. Only with filters
- D. Only in legacy projects
💡 Bonus Insight
Versioning is not only about the backend logic. It affects documentation, client SDKs, and DevOps deployment strategies. Plan for versioning early in your API design.
📄 PDF Download
Need a handy summary for your notes? Download this topic as a PDF!