Why have version in headers and not URLs?

[sujaymansingh]

https://github.com/interagent/http-api-design#version-with-accepts-header

What benefits does this have over having the version in the URL? I'm just curious, I'm not a huge advocate of using the version in the URL.

But with the URL, it's easier to see (logs etc) which version is being used.

[dmathieu]

Logging the appropriate version in the logs is also very easy.
Basically, we don't put the version in the URL because it makes further API evolutions quite hard.
Here are a few interesting reads on the subject:

• http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned
• http://pivotallabs.com/api-versioning/

[geemus]

@sujaymansingh additionally, I would argue that path should just be a reference to an object (and the address shouldn't change between versions, in most cases, even if some behavior and/or representation do change). I like that as a rough guide, similarly keeping headers for meta data (of which I would argue version is one part). Changing/releasing versions is difficult no matter what, but we also have some hope that this will make it slightly easier.

[geemus]

Here is a great blog post about why to prefer headers I just came across: https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

[zdne]

https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

👍