[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: How to know what's supported in REST service 1.1?

Hi Clayton

On 09/01/2012 02:11 AM, Clayton Coleman wrote:
The current plan for the cli is to flexibly tolerate many versions, warn if the server being contacted does not expose a compatible API version, and attempt the operation on the closest version

hmm, to me to completely grock this: how do you achieve this beside the version in the accept-header? You'd check the api version that is reported in the responses and adapt your accept-header?

For on premise there will be several API versions in long term support and the active cli must maintain compatibility for a reasonable period of time.

yes, we have pretty much the same requirements in the openshift-java-client. We expect to have to support different API versions since there'll be different servers available (local/internal installations, openshift.redhat.com, etc.)

We are likely to expose a version test matrix that verifies the newest cli against specific older versions,

yes, we also try to achieve this. We currently have a jenkins build setup that runs integration-tests against PROD, INT, STG etc. We plan to extend this test matrix by the different API versions.

and also implement a mechanism to inform old clients that the should / must update (so that we can blacklist clients that may have data corruption issues).

so you plan to maintain a list of outdated, non-supported APIs and refuse to talk to them when the particular API version is EOL?

We've estimated there are likely to be 5-10 minor API versions a year, with a few major versions.  Flexibly tolerating the presence of new attributes will reduce your potential for breakage, especially on old clients.

sure, completely agree on this basically. The openshift-java-client also simply ignores data that he's not aware of. The cases that are far more difficult to handle are the cases where property contents change semantically or properties even get removed. We're not completely sure how to support these 2 cases so far. I guess that we'll most likely maintain separate client objects for the different, non-compatible APIs. I hope that this will be enough. How are you supporting different non-compatible APIs in the CLI? Do you have distinct libraries for the different API versions?

On Aug 31, 2012, at 6:54 PM, André Dietisheim <adietish redhat com> wrote:

On 08/31/2012 10:50 PM, Lili Nader wrote:
Hi Andre,

Usually, if the change is additive (meaning we add new attributes or resources) we do not increment the version number and the new information is still available in the old version.  

ok. so that would mean that changes that remove properties or change semantics would get pushed to API 1.1, right?
I hope that there wont be too many of them. I'm currently thinking about how the openshift-java-client would support 1.0 and 1.1 (to be able to talk to a 1.0 server at X and 1.1 server at Y) and I currently dont see any golden hammer that would get fail-safe for all kind of changes. The most fail-safe approach would be to drop the strictly typed objects and replace them by loosely typed maps/collections. To be honest I'd love to avoid this if possible. Solved in a less fail-safe but still strictly typed manner would be to provide distinct object hierarchies for the different protocol versions. I'd love if you had some thoughts/hints to share.
Googling for advices on evolution of RESTful API's I found a guide for OpenStack: http://wiki.openstack.org/APIChangeGuidelines
I'd hope that we could stick to something equivalent, since this would make my live much easier. Would you agree/disagree?

I did a search through the code and it seems the only difference between 1.0 and 1.1 is the information returned for a cartridge.  The major difference seems to be the properties attribute returned in 1.0 versus 1.1.

Thanks for looking this up!
You're referring to https://bugzilla.redhat.com/show_bug.cgi?id=838611 right?


----- Original Message -----
From: "André Dietisheim" <adietish redhat com>
To: Dev ex-elb1-prod-1847871222 us-east-1 elb amazonaws com, "Lili Nader" <lnader redhat com>, "Krishna Raman" <kraman redhat com>
Cc: "Xavier Coulon" <xcoulon redhat com>
Sent: Friday, August 31, 2012 12:56:11 AM
Subject: How to know what's supported in REST service 1.1?


Is there any way for us to find out what differs in 1.1 vs. 1.0 protocol 
for the REST service?


dev mailing list
dev lists openshift redhat com

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]