How do you version a Web API, and why?
Quick Answer
Versioning lets you ship breaking changes without breaking existing clients. Common schemes: URL path (/v2/orders — most visible, easiest to route), query string (?api-version=2.0), custom header, or media-type versioning. Pick one and be consistent; URL-path is the pragmatic default.
You version so you can evolve the API without a flag day where every client has to update at once. The approaches are URL path like /v2/, a query-string parameter, a header, or media-type versioning. I usually go with the URL path because it's explicit and trivial to route and cache. The key discipline is only incrementing for actual breaking changes — removing a field, changing a type, tightening validation — because additive changes don't need a new version. When retiring a version I send a Sunset header and give clients a real deadline, and I keep the controllers thin so v1 and v2 both map onto the same domain logic.
- The
Asp.Versioningpackages add[ApiVersion("2.0")], version-aware routing, and Swagger docs per version. - Only bump the version for breaking changes — adding an optional field is backward-compatible.
- Announce deprecation with a
Sunsetheader and a timeline; keep the old version until traffic drains. - Internally, avoid duplicating logic — map both versions' DTOs to one domain model.