Open Stack

HTTP methods are well defined and the system should behave in accordance with those definitions. Otherwise, even saying the word REST is a joke.

On Oct 11, 2011, at 9: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"?
> 

--
George Reese - Chief Technology Officer, enStratus
e: george.reese at enstratus.com    t: @GeorgeReese    p: +1.207.956.0217    f: +1.612.338.5041
enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus - http://www.enstratus.com
To schedule a meeting with me: http://tungle.me/GeorgeReese

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4395 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20111011/2f7b36a0/attachment.bin>