RouteVersioning 1.0.0-alpha.1

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.

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();