title: REST api versioning (only version the representation, not the resource itself)
body: <p>I had a look at <a href="https://stackoverflow.com/questions/389169/best-practices-for-api-versioning">Best practices for API versioning?</a>, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am having two URIs (one with versioning as part of the URI and one without):</p>
  
  <pre><code>http://xxxx/v1/user/123    -&gt; favored solution in discussed thread
  http://xxxx/user/123             
  </code></pre>
  
  <p>I am having my doubts whether the first link expresses the idea of REST. I find <code>http://xxxx/v1/user/123</code> confusing as it suggests that there will be a higher api-version someday like <code>http://xxxx/v2/user/123</code>. But this does not make sense in REST terms, the api version itself is HTTP 1.0 or 1.1, which is already sent inside the HTTP request. This REST resource centric view differs very from other api-interfaces like SOAP or Java-interfaces (where it is common to have api-versions in qualified names).</p>
  
  <p>At REST the only thing where versioning makes sense is the representation of that resource (e.g. new fields are added or removed). This versioning belongs to the part of content-negotiation like:</p>
  
  <pre><code>http://xxx/user/123 + HTTP 'Accept' Header -&gt; Content negotation through header
  http://xxx/user/123?v=1                    -&gt; for perma-links/hyperlinks
  </code></pre>
  
  <p>One could also argue that such version content-negotiation could be part of the URI inside the path, but I find it counter-intuitive, because you could end-up with different URIs for the same resource and have to maintain redirects at some point.</p>
  
  <p>To sum-up: In REST URIs there is no api-versioning, only versioning of the resource's representation. Representation version-info belongs to content-negotiation (as queryParam or HTTP 'Accept').</p>
  
  <p>What do you think? In which things would you disagree/agree?</p>