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



----- Original Message -----
> 
> 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?

When we fetch the api doc we'd specify no version, then check the list of supported versions.  If the command we have needs a specific version and the server supports it, we'd refetch the api doc with the required version (or we'd do the converse where we'd ask for API version X and then if it fails, try without the specific version.  Either way).  api returns the list of supported versions and we'd intersect that with our "known" versions to give a warning.

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

Probably do this by user-agent instead - the scenarios we envision are "dead" clients where they have long been supplanted by newer versions.  Instead of the more generic "the server does not support an API you recognize", we'd have the ability to target clients with certain user agents and give them custom messages - "The OpenShift rhc gem you are using is out of date.  Please run 'gem update rhc'." etc.

I should note that rhc and the console now both send their version number as part of the user agent - see https://github.com/openshift/rhc/blob/master/lib/rhc/helpers.rb#L48.  If the OpenShift Java API is not doing that today I highly recommend us getting that changed as soon as possible.

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

I think we plan on avoiding semantic breaks for as long as possible, by tolerating multiple different properties.  Removal of properties or a change in their meaning should always be a "major" version change and as a consequence we will try to coordinate those removals with all teams.  The addition of new properties will be more common.  I suspect that we will have branching version logic in the CLI with associated tests for both paths, and support both paths as long as feasible (until EOL of the offending server version).  For new attributes we'll probably attempt to abstract/coerce meaning between the two.  We will not have distinct libraries.

> 
> 
> 
> 
> 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?
> 
> 
> 
> Lili
> 
> 
> ----- 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?
> 
> Hi
> 
> Is there any way for us to find out what differs in 1.1 vs. 1.0
> protocol
> for the REST service?
> 
> Thanks
> André
> 
> 
> 
> _______________________________________________
> dev mailing list
> dev lists openshift redhat com
> http://lists.openshift.redhat.com/openshiftmm/listinfo/dev
> 
> 


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