API Versioning

Learning objectives#

• Decide when a change needs a new version
• Configure Asp.Versioning.WebApi with a URL segment
• Run v1 and v2 controllers side by side
• Mark old versions deprecated and report versions in headers

Explanation#

Additive changes (a new optional field, a new endpoint) do not need a new version. Breaking changes do: renaming or removing fields, changing types or meanings, new required inputs.

Install Asp.Versioning.WebApi (the successor of Microsoft.AspNet.WebApi.Versioning). Call config.AddApiVersioning(...) and register the apiVersion route constraint.

URL segments (/api/v1/products) are the easiest to see, cache and test. Query strings (?api-version=2.0) and headers are alternatives.

Put each version in its own namespace (Controllers.V1, Controllers.V2) with [ApiVersion("1.0")] / [ApiVersion("2.0")].

ReportApiVersions = true adds api-supported-versions and api-deprecated-versions headers, so clients learn about deprecations automatically.

Syntax#

1[ApiVersion("2.0")]
2[RoutePrefix("api/v{version:apiVersion}/products")]
3public class ProductsController : ApiController { ... }

Code example: v1 and v2 of the products endpoint#

1using System.Web.Http;
2using System.Web.Http.Routing;
3using Asp.Versioning;
4using Asp.Versioning.Routing;
5

6public static class WebApiConfig
7{
8    public static void Register(HttpConfiguration config)
9    {
10        var constraintResolver = new DefaultInlineConstraintResolver
11        {
12            ConstraintMap = { ["apiVersion"] = typeof(ApiVersionRouteConstraint) },
13        };
14        config.MapHttpAttributeRoutes(constraintResolver);
15

16        config.AddApiVersioning(options =>
17        {
18            options.DefaultApiVersion = new ApiVersion(1, 0);
19            options.AssumeDefaultVersionWhenUnspecified = true;
20            options.ReportApiVersions = true;
21        });
22    }
23}
24

25namespace ShopApi.Controllers.V1
26{
27    [ApiVersion("1.0", Deprecated = true)]
28    [RoutePrefix("api/v{version:apiVersion}/products")]
29    public class ProductsController : ApiController
30    {
31        [HttpGet, Route("{id:int}")]
32        public IHttpActionResult Get(int id)
33        {
34            return Ok(new { Id = id, Name = "Pen", Price = 20m });
35        }
36    }
37}
38

39namespace ShopApi.Controllers.V2
40{
41    [ApiVersion("2.0")]
42    [RoutePrefix("api/v{version:apiVersion}/products")]
43    public class ProductsController : ApiController
44    {
45        [HttpGet, Route("{id:int}")]
46        public IHttpActionResult Get(int id)
47        {
48            // Breaking change: price is now an object with a currency
49            return Ok(new { Id = id, Name = "Pen", Price = new { Amount = 20m, Currency = "INR" } });
50        }
51    }
52}

GET /api/v1/products/1
→ 200 {"Id":1,"Name":"Pen","Price":20.0}
  api-supported-versions: 2.0
  api-deprecated-versions: 1.0

GET /api/v2/products/1
→ 200 {"Id":1,"Name":"Pen","Price":{"Amount":20.0,"Currency":"INR"}}

GET /api/v3/products/1
→ 400 Bad Request — error code UnsupportedApiVersion: the resource does not support API version '3'.

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. The apiVersion constraint is registered so {version:apiVersion} works in route templates.
2. AddApiVersioning sets 1.0 as default and turns on version reporting.
3. Two ProductsController classes live in V1 and V2 namespaces with different [ApiVersion] attributes.
4. v1 is marked Deprecated, so responses advertise that clients should move to v2.
5. Requests for an unknown version get a clear 400 error.

Real-world use case#

Common mistakes#

Best practices#

• Version only for breaking changes
• Keep versions thin over shared services
• Report and deprecate versions explicitly
• Document each version separately in Swagger

Remember this#

Practice exercise#

1using System.Web.Http;
2using Asp.Versioning;
3

4namespace ShopApi.Controllers.V2
5{
6    [ApiVersion("2.0")]
7    [RoutePrefix("api/v{version:apiVersion}/orders")]
8    public class OrdersController : ApiController
9    {
10        [HttpGet, Route("{id:int}")]
11        public IHttpActionResult Get(int id)
12        {
13            return Ok(new { Id = id, Status = "Shipped", Items = new string[0] });
14        }
15    }
16}

Mini quiz#

Want more? Practise all ASP.NET Web API MCQs · ASP.NET Web API interview questions

Related topics#

My notes#

Saved in this browser.