Open Stack

George Reese wrote:

> No, not at all.

> The object is /servers/1234 regardless of the versioning of the API.
It's an object that exists
> independent of your API and its version. A URI should represent a
single, persistent reference to that object.

> The version is really an attribute of the content type you are
accepting. It tells you what kind of content the
> client is expected to send to you and to receive from you. In
particular, the structure of the data representing the persistent
object.

> /servers/1234 should always represent that 1 server. Forever. Unless
the URI has changed, in which case a v1 client will respond
> with a 302 and a v2 client with a 404. A v1 client can then query
/instances/1234 and get the version 1 xml or json. A v2 client
> querying /instances/1234 gets version 2 xml or json.

Another angle on this (which leads to the same conclusion) is to state
that the API has verbs which reference objects.
The object references should not change, ever. It may be possible to
come up with additional methods of referencing
the same objects but even that would be fairly exceptional.

The signature for a given supported verb should also never change.
Period.
New signatures may supplement the existing set, but should very seldom
invalidate a previously valid method signature.

Over time a server will typically end up supporting multiple signatures
to support the same operation, which will include
Some signatures that are now recognized as only supporting a portion of
the clients' requirements.

So, an "API version number" is a short hand method of publishing the set
of method signatures that a server supports.
As a reporting attribute it can be useful, but what is the benefit of
encoding it in the URI?

Essentially when you go form "API version 1" to "API version 2" in the
URIs you are renaming all the signatures. But why
Rename methods that are identical to their prior version? Isn't that
supposed to be the *normal* case?

If you are going to apply version numbers, why not do it on a per method
basis? This is v2 of "GET", etc. Having an overall
Version number to simplify reporting makes sense, by there is no need to
have it in the URI itself. And why have a syntactic
Method for renaming methods? What's so bad about calling this radical
new method "GetV2"?