Add support for header-based versioning

[timotyweis]

Is there a plan to support header based api versioning? There are some folks out there that prefer to use the headers to provide the version information mainly for 2 reasons (see Troy Hunt post ):

• the URL to the resource should not change
• headers are already used for similar purposes, as describing how the data should be returned

Some months ago, I've created my own versioning system taking inspiration by MVC Versioning WebSite and essentially adding the support for header-based versioning (with a HeaderVersionRangeValidator) which is working pretty well (I've added also with Swagger support).
Since it would be nice to use a standardized facility for this, the one that you're building here, I was wandering if there are plans in this direction that will allow me to replace my custom code.

[Duranom]

Doesn't the API-Version-Reader do what you are required to do in the latest version?
It is one line to configure and you can then let the clients send a specific header for an API version request, with just a change to the reader configured you support also the header and query versioning very fast.

[commonsensesoftware]

@Duranom exactly right.

@timotyweis, interesting that you site that particular link. It's one of the first questions asked here. Although it's been closed for a while, issue #42 talks about this in detail with a possible implementation. Succinctly, the issue is that there is no standard, reliable format used in media types that warrants creating an IApiVersionReader implementation out-of-the-box. If the community comes to a consensus on what this media type would look like, I'm happy to entertain including it. From all the methods I've seen, there are at least two common, but distinct way of using media types for versioning. I agree with stable URLs, which is one reason why the query string is the default. The query portion of the URL is technically not part of the path, which is what identifies a resource. I hope that helps.

[timotyweis]

@Duranom thank you for pointing it out. I'll try to replace my own implementation then

@commonsensesoftware thank you for the info, the thread in the #42 issue is really interesting.

Do you plan to support Swagger by providing proper operation filters? Could be an interesting extensions (clearly on both sides)...

[commonsensesoftware]

Re-opening this issue so that it can be linked to the forthcoming PR.

After quite a bit of thought, there is a way to make this work standard and out-of-the-box using a media type parameter. The feature will provide a new MediaTypeApiVersionReader which will use a media type parameter to extract the version from. The default parameter name will be "v", but it can be changed. The value of the parameter will be extracted from the Accept or Content-Type header depending on the type of request being made. If both headers are present, then the Content-Type is preferred as it is the least ambiguous.

The typical setup will look like:

options.ApiVersionReader = new MediaTypeApiVersionReader();

Versioned requests can now be matched with this request:

GET /api/helloworld HTTP/1.1
host: localhost
accept: application/json;v=2.0

POST /api/helloworld HTTP/1.1
host: localhost
content-type: application/json;v=2.0
content-length: 25

{"message":"Hello world"}

If the Accept header has qualities, the first media type with a defined version and the highest quality will be matched. It's possible that the media type support could vary by API version. This seems to be an unlikely or, at least, uncommon scenario. Complex handling for this type of media type negotiation will have to be achieved by developer extension.