On 13/10/2011, at 5:42 PM, Bryan Taylor wrote:
> On 10/12/2011 07:55 PM, Mark Nottingham wrote:
>>> The duplication of effort can be solved by having an intermediary do the
>>> translation. Repose already does this.
>>>
>> That's where there be dragons. Inferring that the user wants to go to
>
On 10/12/2011 07:55 PM, Mark Nottingham wrote:
The duplication of effort can be solved by having an intermediary do the translation. Repose already does this.
That's where there be dragons. Inferring that the user wants to go to version N of the resour
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
On 12/10/2011, at 6:10 PM, Bryan Taylor wrote:
> On 10/11/2011 09:02 PM, Mark Nottingham wrote:
>> While we're talking about versions -- I see that the 1.1 docs allow both URI
>> and media type versioning. That makes me pretty uncomfortable, for a few
>> reasons:
>>
>> * Having two ways to do
It's true that HTTP assigns no meaning to the extension, but HTTP leaves
it to the server to decide the meaning of its own resources and their
location within its URI structure. The filename extension meme is
extremely common for variant resources. We adopt these conventions only
so that that o
The extension has nothing to do with representation in HTTP. It's the content
type (in the headers).
Sent from my iPhone
On Oct 12, 2011, at 17:15, Bryan Taylor wrote:
> On 10/11/2011 10:28 AM, George Reese wrote:
>> It's wildly inappropriate to equate a thing with its representation.
>
> Un
George Reese wrote:
> HTTP methods are well defined and the system should behave in
accordance with those definitions. Otherwise, even saying the word REST
is a joke.
Is your point that because OpenStack APIs should be REST complaint that
there would never be a "V2" on a Get operation? That is
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
On Oct 12, 2011, at 11:23 AM, Soren Hansen wrote:
> 2011/10/11 George Reese :
>> It's wildly inappropriate to equate a thing with its representation.
>
> I didn't say I was right in doing so :)
>
> It's a discussion that gets philosophical rather quickly: Should we
> consider a URI to be a refe
On Oct 12, 2011, at 11:26 AM, Soren Hansen wrote:
> 2011/10/11 George Reese :
>> See EC2 for someone doing it damn well. I've never had to write new code to
>> talk to them unless I want to take advantage of new functionality.
>
> Now I'm confused. EC2 includes the API version in the URI, but I
2011/10/11 George Reese :
> See EC2 for someone doing it damn well. I've never had to write new code to
> talk to them unless I want to take advantage of new functionality.
Now I'm confused. EC2 includes the API version in the URI, but I
thought you were opposed to that?
--
Soren Hansen
2011/10/11 George Reese :
> It's wildly inappropriate to equate a thing with its representation.
I didn't say I was right in doing so :)
It's a discussion that gets philosophical rather quickly: Should we
consider a URI to be a reference to a thing or a reference to a
representation of a thing?
On 10/11/2011 09:02 PM, Mark Nottingham wrote:
While we're talking about versions -- I see that the 1.1 docs allow both URI and media type versioning. That makes me pretty uncomfortable, for a few reasons:
* Having two ways to do it is duplication of effort / more opportunit
On 10/11/2011 09:02 PM, Mark Nottingham wrote:
Linear versioning is of very limited use.
If OpenStack wants to keep a clear definition of what the OpenStack CORE
is, then this needs to evolve linearly (austin, bexar, cactus, diablo,
essex, etc...). I think you could make an argument that this s
On 10/11/2011 10:27 AM, George Reese wrote:
Yes, my proposed solution requires OpenStack implementations to support ALL
major versions of ALL APIs. That's absolutely critical for building a healthy
ecosystem.
That may be completely impossible if different versions require
incompatible underlyi
On 10/11/2011 12:15 PM, Brian Waldon wrote:
That is one case that would require a major version change where a
URI is still valid. However, changes to the URI are still allowed
across major versions. That causes me to think content-types are
not good
It might help to talk about *what* might change, and what kinds of versioning
are available.
E.g.,
* Changing the methods supported by a resource, or their semantics (in the
case of POST)
* Changing the URI query parameters available to a resource
* Changing the range of formats that a res
On 12/10/2011, at 12:51 AM, Mark McLoughlin wrote:
>
> - Version numbers aren't necessarily the best way to advertise the
> availability of features - if we made clients query for the
> availability of the features they're using, you could version the
> features independently.
>
> For
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 ver
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 referen
OK, I get it now :-)
http://en.wikipedia.org/wiki/The_Treachery_of_Images
-
Brian Schott, CTO
Nimbis Services, Inc.
brian.sch...@nimbisservices.com
ph: 443-274-6064 fx: 443-274-6060
On Oct 11, 2011, at 2:53 PM, Lorin Hochstein wrote:
> Ceci
On Oct 11, 2011, at 1:53 PM, Lorin Hochstein wrote:
> Ceci n'est pas un pipe. ;)
Exactly!
-- Ed Leafe
This email may include confidential information. If you received it in error,
please delete it.
___
Mailing list: https://launchpad.net/~
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 con
Putting the version in the URI is a "variant" resource just like adding
.xml or .json . If you want the ability to get to a specific
representation in a browser (as opposed to a custom client) you can't
rely on content negotiation because browsers hard code their accepts clause.
REST is media
Ceci n'est pas un pipe. ;)
--
Lorin Hochstein, Computer Scientist
USC Information Sciences Institute
703.812.3710
http://www.east.isi.edu/~lorin
On Oct 11, 2011, at 11:28 AM, George Reese wrote:
> It's wildly inappropriate to equate a thing with its representation.
>
> On Oct 11, 2011, at 4:06
That is one case that would require a major version change where a URI is still
valid. However, changes to the URI are still allowed across major versions.
That causes me to think content-types are not good enough to handle versioning.
On Oct 11, 2011, at 11:21 AM, Kiall Mac Innes wrote:
> Pret
Yes, my proposed solution requires OpenStack implementations to support ALL
major versions of ALL APIs. That's absolutely critical for building a healthy
ecosystem.
See EC2 for someone doing it damn well. I've never had to write new code to
talk to them unless I want to take advantage of new fu
It's wildly inappropriate to equate a thing with its representation.
On Oct 11, 2011, at 4:06 PM, Soren Hansen wrote:
> I see what you're saying. I guess I'm just used to equating a thing
> with its representation.
>
> --
> Soren Hansen| http://linux2go.dk/
> Ubuntu Developer| http:
Pretending we are talking about "User" resource for me, "kiall" for moment.
The v1 API might represent the kiall user resource as {"name":"kiall"} while
the v2 API might represent the kiall user resource as {"USERname":"kiall"}.
The kiall resource has not changed, only the API representation. Hen
I see what you're saying. I guess I'm just used to equating a thing
with its representation.
--
Soren Hansen | http://linux2go.dk/
Ubuntu Developer | http://www.ubuntu.com/
OpenStack Developer | http://www.openstack.org/
___
Mailing list: htt
Your proposed solution to my example implies we would have to support *all*
major versions of the compute API to some degree. I absolutely don't want to
track redirects from v1 to v2 to v3 to v4 when we are developing v5. That seems
like a painful thing to have to do. We also couldn't guarantee
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
On Tue, 2011-10-11 at 16:40 +0200, Soren Hansen wrote:
> 2011/10/11 Mark McLoughlin :
> > I think the versioning rules below are fine, but there are some other
> > things to think about:
> >
> > - As others raised, what version (if any) should be in the URIs?
> >
> > We could put the full versio
In the example you use, the proper HTTP behavior is for the API should allow
for a HTTP 302 response and clients should follow the permanent move. This
provides both a persistent reference based on the URI and a way to handle the
alteration of URI structure.
-George
On Oct 11, 2011, at 2:56 PM
On Tue, Oct 11, 2011 at 9:56 AM, Brian Waldon
wrote:
> I'm not sure I agree with that. A URI should be a persistent reference to a
> resource within the context of a major version of an API. Between major
> versions, the URI structure can change completely (for example /servers ->
> /instances)
ces+biermana=brocade@lists.launchpad.net] On Behalf
Of Brian Waldon
Sent: Tuesday, October 11, 2011 5:40 AM
To: Bryan Taylor
Cc: openstack@lists.launchpad.net
Subject: Re: [Openstack] OpenStack API Versioning Conventions
I'm all for exposing only the major version in the URI (/v1). We have fallen
2011/10/11 Mark McLoughlin :
> I think the versioning rules below are fine, but there are some other
> things to think about:
>
> - As others raised, what version (if any) should be in the URIs?
>
> We could put the full version number in the URIs so long as we
> maintain support for the older
Thanks for the feedback, Mark! Comments inline:
On Oct 11, 2011, at 9:51 AM, Mark McLoughlin wrote:
> Hi Brian,
>
> I think the versioning rules below are fine, but there are some other
> things to think about:
>
> - As others raised, what version (if any) should be in the URIs?
>
> We could
2011/10/11 George Reese :
> Versioning should not be included in the URI. It belongs in the headers. A
> URI should be a persistent reference to a resource. As such, versioning
> always breaks that persistent reference.
I don't follow. If the version is included in the URI, that's got to
be a mo
I'm not sure I agree with that. A URI should be a persistent reference to a
resource within the context of a major version of an API. Between major
versions, the URI structure can change completely (for example /servers ->
/instances), destroying your persistent reference.
Additionally, if we o
Hi Brian,
I think the versioning rules below are fine, but there are some other
things to think about:
- As others raised, what version (if any) should be in the URIs?
We could put the full version number in the URIs so long as we
maintain support for the older, compatible versions i.e. t
Versioning should not be included in the URI. It belongs in the headers. A URI
should be a persistent reference to a resource. As such, versioning always
breaks that persistent reference.
-George
On Oct 11, 2011, at 1:40 PM, Brian Waldon wrote:
> I'm all for exposing only the major version in
I'm all for exposing only the major version in the URI (/v1). We have fallen
into a trap with v1.0 and v1.1 as they are not backckwards-compatible specs
while their versioning implies they are. I think we can have a whole separate
discussion on how to solve that problem, so like I said earlier,
On 10/11/2011 12:26 AM, Mark Nottingham wrote:
> Where would these versions show up? In URLs? In documentation? In
> response payloads?
>
> If they show up in URLs, then every backwards-compatible change would
> be made into a backwards-incompatible change. E.g., if you had
>
> http://www.example
Where would these versions show up? In URLs? In documentation? In response
payloads?
If they show up in URLs, then every backwards-compatible change would be made
into a backwards-incompatible change. E.g., if you had
http://www.example.com/v1.2.3/foo
as a resource, and adding a new resource .
Yep, I think we're in agreement. Version 1 should always be backwards
compatible. Once we need to make a backwards incompatible change, we need to
talk about version 2.
Waldon
On Oct 10, 2011, at 2:11 PM, George Reese wrote:
> API implementations should always be backwards compatible. The beha
API implementations should always be backwards compatible. The behavior should
be dependent on the client's requested version.
The only thing that should not propagate is bugs.
On Oct 10, 2011, at 2:55 PM, Brian Waldon wrote:
> In talking with several people at the Design Summit about the OpenS
I'm totally for everything you said. Versioning should absolutely be separate
from the code. That is exactly what I was pushing for in my original proposal.
I was planning on continuing the discussion w.r.t. how to expose these versions
after we agree on the actual structure of the versions them
I think we should separate versioning APIs from code. Client needs
should drive API versioning.
Generally, I agree we should focus versioning on backwards compatibility
and feature sets, but REST is supposed to be media type centric, so I'd
like to see separate versioning around data formats t
Just to clear up some questions I have already gotten: The revision numbers are
designed only to advertise additions to the spec, wether they be new fields or
whole resources. The revision number does not advance if we make a bug fix
within Nova, as the spec itself needs to evolve independently
In talking with several people at the Design Summit about the OpenStack Compute
API, I have come to the conclusion that our current method of versioning is
broken. I would like to propose that as we move forward, we adopt the following
API versioning conventions:
1) Use a three-part version num
51 matches
Mail list logo
