In Enterprise software, you can almost never "Turn Off" an old API. You must support multiple versions at the same time to avoid breaking your customers' apps.
The most common and visible way. **Pros:** Very easy for users to understand and for proxies to cache. **Cons:** It violates the principle that a 'Resource' (a User) should have a single URI. When you move to v2, the URI of the same user changes.
The URL stays the same; the version is hidden in the metadata. **Pros:** Clean URLs. **Cons:** Harder to test in a browser directly and can break some CDNs that don't cache based on custom headers.
Don't roll your own versioning logic. Use the official Microsoft library. It allows you to use attributes:
[ApiVersion("1.0")]
[ApiVersion("2.0")]Q: "When should we 'Deprecate' an API version?"
Architect Answer: "We use a **Sunset Policy**. When v2 is released, we mark v1 as 'Deprecated' in the headers (`Sunset: Sat, 31 Dec 2024`). We monitor our logs to see which customers are still using v1 and contact them proactively. We never turn off an API until its usage reaches <1% or the support cost exceeds the value provided by those remaining customers."