RouteVersioning 1.0.0-alpha.4

RouteVersioning

Route-based API versioning for ASP.NET Core. This library works by exhaustively mapping all corresponding API versions, on startup. Only minimal APIs are currently supported.

The following packages are available,

• RouteVersioning
• RouteVersioning.OpenApi

⚠️ Warning

This project is a work in progress!! The examples below will likely change as I finalise its APIs. My to-do list is:

• Minimal APIs
• OpenAPI
• Sunset header
• Tests
• NuGet package
• Controllers, if possible?

Usage

Mapping a Versioned API

1. Define all available API versions with a RouteVersionSetBuilder.

   // In this case, the API has 3 versions.
   var versions = new RouteVersionSetBuilder<int>()
    .Version(1)
    .Version(2)
    .Version(3)
    .Build();
   

2. Use WithVersions to map versioned endpoints, specifying the range of versions to which they apply.

   var api = app.MapGroup("api").WithVersions(versions);
   

   • Use From to map an endpoint that is available from a specific version onward.

     // api/v1/a (introduced)
     // api/v2/a (unchanged)
     // api/v3/a (unchanged)
     api.From(1).MapGet("a", () => ...);
     
     // api/v2/b (introduced)
     // api/v3/b (unchanged)
     api.From(2).MapGet("b", () => ...);
     
     // api/v3/c (introduced)
     api.From(3).MapGet("c", () => ...);
     

   • Use Between to map an endpoint that is available in all versions within an inclusive range of versions.

     // api/v1/d (introduced)
     // api/v2/d (unchanged; retired)
     api.Between(1, 2).MapGet("d", () => ...);
     

   • Combine the two to revise an endpoint at a specific version.

     // api/v1/e (introduced)
     // api/v2/e (unchanged)
     api.Between(1, 2).MapGet("e", () => ...);
     
     // api/v3/e (revised)
     api.From(3).MapGet("e", () => ...);
     

Retiring an API Version

• Use Sunset to indicate an API version being retired, which adds the specified details as Sunset and Link headers as described in RFC 8594, to its responses.

  var versions = new RouteVersionSetBuilder<int>()
    .Version(1, (v) => v
    	.Sunset(
    		at: someDateTime,
    		link: "https://example.com/changelog/v2-migration",
    		linkMediaType: "text/html"
    	)
    )
    .Build();
  

  HTTP/1.1 200 OK
  Sunset: Tue, 24 Dec 2024 12:41:24 GMT
  Link: <https://example.com/changelog/v2-migration>; rel="sunset"; type="text/html"
  

Adding Endpoint Conventions

• To add a convention that applies to a specific endpoint across a range of API versions (v*/a), add a convention as you normally would, after the Map* call.

  api.Between(1, 2).MapGet("a", () => ...).AddEndpointFilter<UwuifyFilter>();
  api.From(3).MapGet("a", () => ...).AddEndpointFilter<UwuifyFilter>();
  

• To add a convention that applies to all endpoints of a specific API version (v1/*), use the configuration delegate of RouteVersionSetBuilder.Version.

  var versions = new RouteVersionSetBuilder<int>()
   	.Version(1, (v) => v
    	.AddEndpointFilter<IEndpointConventionBuilder, UwuifyFilter>()
    )
   	.Build();
  

Alternatives

If you're after a library that supports versioning using query parameters, request headers, content negotiation, etc., consider Asp.Versioning which should be capable of everything that this library offers, with some configuration. Comparatively, this one,

• Offers just one API versioning scheme (route-based).
• Maps all versions at startup, instead of resolving API versions as requests are made (as I understand).
• Uses API version ranges (i.e., vX-onward/between vX & Y inclusive) by default.