API Versioning

I recently had to look at API versioning for ASP.NET Core 2.0 APIs for work. We looked at aspnet-api-versioning and contrasted that with Troy Hunt’s You are doing API-versioning wrong […].

We had decided we didn’t want to version controllers but rather the individual actions.

Initial approach

We all went off and looked at various solutions end-to-end and will compare notes tomorrow.

I tried a variation of Troy Hunt’s VersionedRoute attribute – but based on the IActionConstraint attribute for ASP.NET Core – that applies a regular expression to the accept header to determine the version to select. Initial testing showed promise.


Swashbuckle does not enjoy multiple actions with the same route in the same Swagger document. By using operationfilters to keep versions of the same actions in separate SwaggerDocs we could get the page to load without error.


By figuring out the highest version of any action in the API I generate one SwaggerDoc for each, including either actions with that specific version – or the highest version of operations that only have lower versioned actions or of course unversioned actions.

That way, if you just load the swagger page – you only see the newest versions. Weirdness only sets in when you try to operate the versions dropdown, but even then it kind of makes sense.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s