A URI version, and why it beat a header

Three ways to version an API, and choosing the one that is visible in a log line.

  a header          Accept: application/vnd.td.v2+json
    correct by the book. invisible in an access log,
    invisible in a browser, and a consumer who omits
    it gets a default that changes meaning over time.

  a query parameter  ?version=2
    caches badly, and mixes a routing concern with a
    filtering one.

  the URI            /api/v2/orders
    inelegant, and:
      grep-able in the access log
      visible in a bug report
      cacheable without a Vary header
      testable with curl and no flags

The header approach is more correct and the URI approach is more operable, and after six years of never needing a version the deciding factor was which one somebody can debug at three in the morning. Every argument against URI versioning is aesthetic and every argument for it is operational, which is not a universal law and was the right weighting here.