Versioning an API in the URL is honest and ugly

Every API versioning scheme is a trade between visibility and purity, and the URL version is the one nobody can get wrong.

/v1/orders           visible in every log, curl, and
                     browser bar. cacheable. inelegant.

Accept: application/vnd.api+json; version=1
                     purer, and invisible in a log; a
                     client that omits it gets a default
                     it did not choose.

?version=1           interacts badly with caching, and
                     with every query-string parser.

The argument against URL versioning is that a resource should have one identifier regardless of representation, which is correct and has never once helped anybody debug a production incident. The header approach is defensible when there is a strong client story and a default that fails loudly rather than silently. Whatever is chosen, the version has to appear in the access log, because otherwise nobody can tell which clients are on what.