It solves the problem of client-server communication. This is the same idea as with: "GET /car HTTP/1.0" and "GET /car HTTP/1.1" . It provides a clear way to specify which protocol the client speaks, while allowing the URI to stay the same. Contrast this with: "GET /v1/car" and "GET /v2/car".
The article simply uses the Accept: header to achieve the same.
But how is this better in practice? Why is it important that the URI stay the same? I don't see why coding the version information in the header is better than coding it in the URI. The latter seems much easier to manage in practice.
If you leave the version out of the URL, the same URL can represent multiple versions/renderings of the same resource.
This makes sense conceptually, as /users/22 is the same user, whether you are getting the data in version 1 of the XML rendering, or version 6 of the JSON rendering, or even an HTML page or snippet representing the user. The Accept header can handle all of this.
There is also the advantage that when returning links to other resources -- e.g. GET /users returning an array of users, each specified by a URI like /users/22 -- the server does not need to prescribe a version for the client. The server just returns the link to the resource, and the client Accepts whichever format/version it wants.
I would contend that API versions are a fundamental part of a resource. A resource is defined by its content and available operations. Changes to an API redefine the content and operations of resources. That redefinition makes different API versions distinct resources from each other.
Also, api clients shouldn't give a damn about URI structure/content. If they aren't using links embedded within the representations you present then your "RESTful" API has bigger problems than the where-to-hide-the-version game.
I would contend that API versions are a fundamental part of a resource. A resource is defined by its content and available operations. Changes to an API redefine the content and operations of resources. That redefinition makes different API versions distinct resources from each other.
Consider that a server may choose to provide the same resources in one of multiple versions and renderings, for instance to support older clients alongside new ones. I would consider it surprising if altering a resource at e.g. /v1/users/22 would also alter resources at other URLs, like /v2/users/22.
In addition, keeping version out of the URL allows the resources to be cross-referenced between different client apps, which are not necessarily browser-bound. One client expects the latest and greatest version, one client expects an older version, and they can pass data back and forth freely.
Also, api clients shouldn't give a damn about URI structure/content. If they aren't using links embedded within the representations you present then your "RESTful" API has bigger problems than the where-to-hide-the-version game.
I agree, but I'm talking about returning e.g. /users/22 instead of /v1/users/22 or /v1/users/22.json, not instead of 22.
In this example, the client knows what version it can handle and should specify that separately than the user providing the URI for the desired resource. Separation of concerns. Why make the end user guess about version numbers?
Why is the end user putting in the URI for a web service? I'm confused. If the client knows what versions of the web service it can work with, the client can also know the correct URIs for different versions.
The article simply uses the Accept: header to achieve the same.