[openstack-dev] Proposal for API version discovery

Jamie Lennox jlennox at redhat.com
Wed Jul 24 05:41:51 UTC 2013

On Thu, 2013-05-02 at 00:46 +0000, Gabriel Hurley wrote:
> Based on input from several of the PTLs (and others), I'd like to propose the following outline for how version discovery should be handled across heterogeneous clouds:
> https://etherpad.openstack.org/api-version-discovery-proposal
> Further discussion is absolutely welcome, and I would like to propose it as a topic for review by the Technical Committee at the next meeting since it involves a significant cross-project standardization effort.
> All the best,
>     - Gabriel

So I started on this somewhat independently before i found the blueprint
and given I have a semi working implementation i've got a few questions
or essentially an area i find inconsistent.

AFAIK there are no other serious attempts at this so i've got nothing to
go off. Also for the time being I don't care about HATEOS, or future
discovery protocols, just getting something that works for keystone now.

I think the way version is treated in the current blueprint is off.
Looking at 'Auth with a Specified Version' point 2 says that we should
not infer the version from the URL and point 3 says that if i provide a
version number with a non-versioned endpoint to retrieve possible
versions and instantiate a client if an endpoint is available for that

I don't think that we should be checking the url for what is and what
isn't a versioned endpoint for the same reasons we shouldn't be
retrieving the version from the URL. 

What i would like to do is treat the version parameter as the requested
version, rather than using it to prevent a lookup for versions. What
this means is that i can say: 
        client.Client(auth_url="http://example.com:5000/", user=foo,
        version=2.0, ...)
and retrieve a version 2 client from a provider that may provide both
versions v2 & v3. This will still require a lookup of the auth_url even
though version is specified. 

Keystone (not sure on others) provides version information at GET /v2.0
(and other versions) as well as GET / so if i say:
        version=2.0, token=foo)
It should be validated that the endpoint is capable of using the V2 api
and doing:
        version=3.0, token=foo)
should fail immediately.

To summarize: every call to client.Client should result in a query to
check available versions. The version parameter is an indicator of what
version client should be retrieved from those specified as available and
it should fail if it can't deliver. If you _really_ want to use a
particular client without a lookup you should use the original
keystoneclient.v2_0.Client which is what is returned from a successful
client.Client (with version=2) call anyway and takes the same

I've posted the work for review: https://review.openstack.org/#/c/38414/
and would appreciate comments/clarification. 



> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list