On 09/05/2012 06:53 PM, Clayton Coleman wrote:
----- Original Message -----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.
ok got it, pretty much enlightning, thanks a lot!
So basically - if I get it right, you'll have a common lib for all versions and handle versions by branching logic. You'll track the required API for each operation and branch internally. I guess that this is simpler for a command line driven tool than it is for a lib that holds a state. We actually offer objects to users, that reflect the openshift resources (applications, domains, etc). I guess that we'll have to maintain distinct objects for each major version (while inheriting common logic/states). Please correct me if you think that I'm wrong.. ;)
good point, thanks for reminding. But we actually do, since quite a long time. We send a custom user-agent that also includes the client lib version: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.
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.
Yes, we'd highly appreciate being informed about breaking changes since this is pretty crucial for us.