4

With routing done by controller name (unless route set for each controller/action), I see the only benefit of using the ApiVersion attribute in having versioned APIs use the same controller name but in separate namespaces.

Otherwise the proper use that I have found is:

[ApiVersion("2.0"]
[RoutePrefix("api/v{version:apiVersion}/test")]

I do not see any efficiency or productiviy gain here when this must be applied across the board, there is no difference in dropping the package and simply using this:

[RoutePrefix("api/v2.0/test")]

I can only assume that I am missing something obvious here.

Marcus Aurelius
  • 61
  • 2
  • The following link may help you to understand the concept [https://stackoverflow.com/a/22217668](https://stackoverflow.com/a/22217668) – Saveen May 16 '18 at 05:51

1 Answers1

1

There is a laundry list of benefits; far too many to all list here. Here's an attempt to cover some of the most common, high-level benefits:

  • An API Version is a first-class type and not a magic string. 2.0 and 2 are semantically equivalent; therefore, api/v2.0/test and api/v2/test are the same resource.

  • You do not have to use attributes. This one of several ways to you can apply API versions. You can also use conventions.

  • There is a built-in convention to support an implicit API version derived from the containing source code namespace.

  • Multiple versioning styles are supported (query string, URL segment, header, media type) or you can plug-in your own method.

  • API version to method mapping. A single controller might support multiple API versions, which is referred to as version interleaving. You can map different action methods to be called on a single controller type, while defining a single route template. (ex: 1.0 might map to GetV1 and 2.0 might map to GetV2).

  • API version advertisement, which gives a way for you to inform your clients which API versions are supported and/or deprecated per API.

  • API Explorer support, which collates your APIs by version and be used with Swagger/OpenAPI documents, etc.

Chris Martinez
  • 3,185
  • 12
  • 28