Put it in the URL. /v1/customers. I know the arguments against it, I think several of them are
correct in theory, and I still think URL versioning wins on every practical dimension that matters.
It is visible in a log line, a browser bar, a support ticket screenshot, and a curl command. It is cacheable by anything that caches URLs. It is trivially routable at the gateway. It requires zero explanation to a new consumer. And when someone pastes you a URL, you know immediately which version they are on.
Header or media-type versioning is more theoretically correct — the resource is the same resource, only the representation changed — and in practice it makes every debugging conversation start with “what headers are you sending?” It hides the most operationally important fact about a request inside metadata that half your tooling will not show you.
The much more important question is the one underneath: what are you versioning for? A version number is a communication device for breaking changes. Most changes should not need one. Adding a field, adding an endpoint, adding an optional parameter — those are additive and should ship without a new version. Save the version bump for the changes that genuinely break somebody, and then commit to running both versions long enough for them to migrate.
