openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

On Oct 11, 2011, at 4:10 PM, Caitlin Bestler wrote:

> 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"?

I feel like our real product is Nova, and the Compute API is just the interface used to communicate Nova's current state to Nova's clients. Yes, the Compute API is a separate product (and should develop independently of Nova), but without Nova, there would be no need for an API. My point here is that we are designing an HTTP API to expose an underlying system, we aren't designing a pure REST API service. For example, Twitter is nothing without its API. If we turned off our API, you could still ssh into your instances or use nova-manage, which bypasses the API altogether. Your point above about the API being composed solely of different method signatures available to interact with the core objects would be valid if we wanted the API to own those objects. At the end of the day, Nova is going to own an instance, not the API that exposes it.

Brian Waldon