openstack team mailing list archive

[Mark Nottingham <mnot@xxxxxxxx>]

On 13/10/2011, at 3:15 AM, Bryan Taylor wrote:

> On 10/11/2011 10:28 AM, George Reese wrote:
>> It's wildly inappropriate to equate a thing with its representation.
> 
> Unless the thing is itself a representation, yes. A resource can be ANYTHING: a server, a database record about a server, a car, a rock, the concept of love, the act of smiling, or a representation of a second resource, etc...
> 
> http://example.com/thing is the thing
> http://example.com/v1/thing is the set of v1 representation of the thing
> http://example.com/v2/thing is the set of v2 representation of the thing
> http://example.com/v1/thing.json is the v1 JSON representation of the thing
> http://example.com/v2/thing.xml is the v2 XML representation of the thing

Those are all different things in HTTP, by the virtue of having different URIs. You can make relations between them using links (see RFC5988 for a way to do that), but they're separate resources, by definition.

For example, if you change the state of /v1/thing, it may or may not have an effect upon the state of /v2/thing; that's completely hidden in the implementation of the server, not visible to HTTP. 

If it's really the same thing, it should have the same URI, and different representations. If you don't want to do server-driven conneg for formats, that's fine, but realise that it's going to cause some problems when you need to unambiguously identify the thing. 

WRT versioning -- if it's the same thing, there's no need to surface the underlying implementation changes in the URI. If there are enough changes to warrant a new URI version name space, that's great, but there isn't any natural transfer of semantics between versions -- that robs you of the ability to remove, rename or move things in the API between major versions (which again, should be very very rare, ideally non-existant).

> 
> A resource that represents a representation or set of representations of second resource is called a variant resource of the other.
> This email may include confidential information. If you received it in error, please delete it.
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

--
Mark Nottingham   http://www.mnot.net/